Use the CLI and MCP Server Together

TL;DR

• •MCP = live decisions. Tool results land directly in the agent's context and feed the next reasoning step.
• •CLI = materialized state. Output goes to stdout or disk, so the agent can read only the files and fields it needs.
• •Same workspace, same auth. Both use AGENTLED_API_KEY, optional AGENTLED_URL, and the same @agentled/core behavior under the hood.

Install + Auth

Install the CLI globally if this machine will work on AgentLed projects often. Use npx for one-off or CI-style calls.

npm i -g @agentled/cli

# or run without installing
npx -y @agentled/cli help

Register the MCP server with your client. Claude Code uses this form:

claude mcp add agentled \
  -e AGENTLED_API_KEY=wsk_... \
  -- npx -y @agentled/mcp-server

Codex and other MCP clients use the same server process:

codex mcp add agentled \
  -e AGENTLED_API_KEY=wsk_... \
  -- npx -y @agentled/mcp-server

Create a workspace API key in Workspace Settings > Developer. Export it for CLI calls and pass it to your MCP client config.

export AGENTLED_API_KEY=wsk_...
export AGENTLED_URL=https://www.agentled.app

agentled workspace inspect --format json

AGENTLED_URL is optional for the managed platform. Set it only when your workspace uses a custom AgentLed API base URL.

When to Use Which

Rule of thumb: if the answer needs to fit in one paragraph the agent reasons about, use MCP. If the answer is “make this file appear”, use the CLI.

# Bulk data: keep it out of the model context.
agentled workflows list --format json > /tmp/agentled-workflows.json

# Then inspect only what matters.
rg '"status": "live"|outbound|scoring' /tmp/agentled-workflows.json

The Canonical Loop

This is the zero-credit iteration path. Run the workflow once, capture real step outputs, then replay tests from fixtures while you edit. Step 6 is the unlock: after fixtures are on disk, the normal test loop costs no credits.

# 1. Create the local workspace folder once.
agentled init acme

# 2. Orient and pick a workflow.
agentled workspace inspect --format json > agentled_acme/workspace.inspect.json

# 3. Pull a workflow into the local workspace.
agentled workflows pull <wfId>

# This writes the workflow JSON and a test skeleton.
# Edit tests/<wfId>.test.json before the first replay.

# 4. Use MCP for the one live execution.
# Call start_workflow with representative sample input.
# Save the returned execution id as <execId>.

# 5. Capture real step outputs from that execution.
agentled fixture capture <execId> --wf <wfId>

# Fixtures land in fixtures/step-outputs/<execId>/.
# They become local, replayable test inputs.

# 6. Replay assertions with zero credits.
agentled test <wfId>

# 7. Edit pipeline JSON, prompts, mappings, or test assertions.
# 8. Replay the full test suite again.
agentled test <wfId>

# 9. When one step needs a live check, spend narrowly.
agentled test <wfId> --step score-lead --live

# 10. Validate before publishing.
agentled workflows lint examples/live/<workflow>.json
agentled dryrun examples/live/<workflow>.json
agentled workflows validate <wfId>

# 11. Use MCP to publish when validation is clean.
# Call publish_workflow with workflowId=<wfId> and status=live.

Use MCP during this loop for decisions that belong in the conversation: choosing the workflow, starting the single live run, editing one step with update_step, checking validation results, and publishing. Use the CLI for everything that creates or reads local state.

Pre-flight Before You Spend Credits

Run these checks before start_workflow or any live agentled test --live. Exit codes are stable: 0 clean, 1 warning, 2 error.

agentled workflows lint examples/live/<workflow>.json
agentled dryrun examples/live/<workflow>.json
agentled workflows validate <wfId>

workflows lint catches static gotchas in the file. dryrun walks the graph, resolves template references against mock or captured outputs, and estimates credits. workflows validate <id>runs the server-side validator after the workflow exists in AgentLed.

Fallback-protected refs such as {{x || 'default'}} are warnings, not errors. The runtime can resolve them through the fallback, but the warning tells the agent that the primary path may be absent.

Mirrored vs Surface-only Operations

Mirrored

CLI-only

MCP-only

Orientation in a Fresh Repo

When an agent lands in a repository, it should look for an agentled_*/ folder in the current directory or any ancestor first. That folder is the persistent working memory for the workspace. It contains pulled workflows, tests, fixtures, cached app metadata, and local docs.

If no workspace folder exists, run agentled init [slug] once. Then run agentled workspace inspectfor a single-shot orientation: identity, company profile, workflows, Knowledge Graph lists, connected apps, and agents. For deep work on one workflow, follow with agentled workflows pull <wfId>.

# From the repo root:
find .. -maxdepth 3 -type d -name 'agentled_*' 2>/dev/null

# If none exists:
agentled init acme

# Orient once, then pull the workflow you are changing.
agentled workspace inspect --format json > agentled_acme/workspace.inspect.json
agentled workflows pull <wfId>

Error Model

Both surfaces speak JSON. The CLI gives agents stable process signals. MCP gives agents structured tool results.

Treat 1 as warning or recoverable failure and 2 as a structural or validation error. In unattended scripts, stop on 2 and print the validator output.

Admin Patch Tools

patch_timeline_fields and patch_execution_fields exist for incident response. They require an API key with the admin:patch scope. Do not use them for routine workflow operation, normal retries, fixture generation, or step edits. If you reach for them repeatedly, the workflow is misconfigured and should be fixed at the source.

Next Steps

• MCP Connection — connect your MCP client.
• MCP Tools Reference — inspect available tools.
• agentled create — create workflows from natural language.