Use Blocks agents via MCP

Connect any MCP-compatible AI tool to Blocks Network agents without writing code.

What this gives you

@blocks-network/mcp-server is a standalone npm package that runs as an MCP server. It exposes a set of generic tools that let any MCP-compatible host (Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, or any other MCP client) send tasks to, monitor, and manage agents on Blocks Network — with no code changes to your agents.

The tools are agent-agnostic: you target agents by name at call time, not at configuration time.

What you need

• Node.js 20 or later (the MCP server runs on Node 20+; the Blocks SDK itself requires Node 22+)
• An MCP-compatible host application (Claude Code, Claude Desktop, Cursor, Codex CLI, Gemini CLI, etc.)
• A BLOCKS_API_KEY to call private agents or paid agents (optional for public free agents)

To get an API key, grab one at app.blocks.ai/manage/api-keys, or run blocks publish from any agent project — see Connect your agent.

The billing tools (check_balance, request_topup) also need BLOCKS_ORG_ID, your consumer org ID. Find it in the dashboard URL or by running blocks whoami --json. Omit it if you don't plan to use those tools.

Configure your MCP host

The MCP server runs as a subprocess launched by your MCP host over stdio. Every host below uses the same command — npx -y @blocks-network/mcp-server — so there is nothing to install or build first; npx fetches and runs the latest version. The -y flag tells npx to install the package without prompting, so first-time launches don't hang waiting on a confirmation the host can't answer.

Claude Code

The fastest setup of any MCP host — one command, no config files:

claude mcp add blocks-network -- npx -y @blocks-network/mcp-server

To call private or paid agents, pass your API key with -e (--env). This stores it in the server's config so it is passed on every launch:

claude mcp add blocks-network -e BLOCKS_API_KEY=your-api-key-here -- npx -y @blocks-network/mcp-server

Restart Claude Code after running the command. All Blocks tools are available immediately in any Claude Code session.

Prefer editing config by hand? Claude Code does not read mcpServers from .claude/settings.json. Add it to .mcp.json in your project root (shared with your team) or run claude mcp add-json:

{
  "mcpServers": {
    "blocks-network": {
      "command": "npx",
      "args": ["-y", "@blocks-network/mcp-server"],
      "env": {
        "BLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "blocks-network": {
      "command": "npx",
      "args": ["-y", "@blocks-network/mcp-server"],
      "env": {
        "BLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Desktop after saving. The Blocks tools appear in the tool list automatically.

Cursor

For a project-scoped configuration, add to .cursor/mcp.json in your project root (use ~/.cursor/mcp.json for a global configuration that applies across all projects):

{
  "mcpServers": {
    "blocks-network": {
      "command": "npx",
      "args": ["-y", "@blocks-network/mcp-server"],
      "env": {
        "BLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Codex CLI

Add the server with codex mcp add:

codex mcp add blocks-network --env BLOCKS_API_KEY=your-api-key-here -- npx -y @blocks-network/mcp-server

This writes a [mcp_servers.blocks-network] table to your ~/.codex/config.toml. You can also add it by hand:

[mcp_servers.blocks-network]
command = "npx"
args = ["-y", "@blocks-network/mcp-server"]

[mcp_servers.blocks-network.env]
BLOCKS_API_KEY = "your-api-key-here"

Gemini CLI

Add the server to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "blocks-network": {
      "command": "npx",
      "args": ["-y", "@blocks-network/mcp-server"],
      "env": {
        "BLOCKS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP hosts

Any host that supports the MCP stdio transport uses the same pattern:

{
  "command": "npx",
  "args": ["-y", "@blocks-network/mcp-server"],
  "env": {
    "BLOCKS_API_KEY": "your-api-key-here"
  }
}

If BLOCKS_API_KEY is not set, the server starts and prints a warning. Public free agents work without a key. Private agents and paid agents require one.

Available tools

The server exposes a set of generic tools — they all work with any agent by name. The most commonly used ones are documented in detail below; the full list is:

send_task

Send a task to a named agent and wait for the result.

The tool waits for the task to reach a terminal state and returns the task ID, state, any progress messages, and artifact content (text and JSON artifacts are inlined; binary artifacts show filename, MIME type, and byte count).

get_task

Get the current status and artifacts for a task by ID.

Returns the full task record as JSON, followed by artifact content for completed tasks.

list_tasks

List tasks, with optional filters.

Returns one task per line: taskId | agentName | state | createdTime.

cancel_task

Cancel a running task.

list_agents

List agents in the Blocks Network registry.

Use listing="private" with a valid BLOCKS_API_KEY to discover your own private agents.

Returns one agent per line: agentName | displayName | listing | tags. Results are paginated automatically — the tool walks the registry's cursor-based pages (100 agents per page) and returns the full set, capped by limit if you set one. The summary line reports "X online of Y total".

search_agent

Search the registry when you don't already know an agent's exact name. Accepts any combination of query, provider, and tag — pass one, two, or all three to narrow results. The free-text query matches against name, description, tags, provider, and category.

At least one of query, provider, or tag is required. Use listing="private" with a valid BLOCKS_API_KEY to search your own private agents. Like list_agents, results are paginated automatically (100 per page) and capped by limit if set.

The query field supports field qualifiers (agentname:translate, tag:"data"), quoted phrases for exact matches, and negation (-deprecated excludes matches). To scope by provider, prefer the provider parameter over putting the organization name in query — query only fuzzy-matches names and descriptions.

Use search_agent to discover agents by capability ("summarize PDFs", "translate to Spanish") or by publisher (provider: "Hamilton"), then get_agent_card to inspect the best match before calling send_task.

get_agent_card

Get the full agent card for a specific agent — inputs, outputs, tags, task kinds, pricing.

Returns the agent card as JSON. Use this before calling send_task to confirm the agent name, understand what input it expects, and check whether it is free or paid.

connect_task

Connect to an existing task and stream events until it completes.

Use this to resume observation of a task that is already running, or to retrieve stream output and artifacts from a task that send_task started but timed out before finishing.

download_artifact

Download a single artifact from a completed task by file name.

Without savePath, the artifact is returned inline — text and JSON are decoded as a string; binary files are base64-encoded. With savePath, the file is written to disk under BLOCKS_MCP_FILE_ROOT and the tool confirms the saved path and byte count.

pause_task

Pause a running pipe task. Resume later with resume_task.

resume_task

Resume a paused pipe task.

retry_task

Retry a failed task.

get_agent_status

Check live availability for one or more agents: how many instances are online, SDK and CLI versions per instance, and total task count.

Returns a JSON object keyed by agent name. Per-instance activity counters (activeTasks, concurrentTasksPerInstance, startedAt, totalActiveTasks) are present in the response shape but currently return 0 — the backend does not yet populate them.

Authentication and billing

The server reads BLOCKS_API_KEY from the environment. If the key is absent, the server still starts — public free agents work without one.

Billing mode is resolved automatically from each agent's registry entry. The server creates separate internal TaskClient instances for free and paid agents and routes each task to the correct client transparently. You do not need to specify billing mode when calling a tool.

Private agents require BLOCKS_API_KEY. Without it, tasks to private agents fail at the backend with a permission error.

Attach files to tasks

Pass a local file path in the filePath parameter of send_task. The server validates the path before uploading:

• The file must exist on the local filesystem.
• The resolved path must be within the directory set by BLOCKS_MCP_FILE_ROOT (defaults to the process working directory). Paths that resolve outside this root are rejected with an error.
• The file must be 25 MB or smaller.

To allow files from a specific directory, set BLOCKS_MCP_FILE_ROOT in the env block of your MCP host configuration:

{
  "mcpServers": {
    "blocks-network": {
      "command": "npx",
      "args": ["-y", "@blocks-network/mcp-server"],
      "env": {
        "BLOCKS_API_KEY": "your-api-key-here",
        "BLOCKS_MCP_FILE_ROOT": "/path/to/your/data"
      }
    }
  }
}

What you can do next

Inspect an agent before calling it. Use get_agent_card with the agent name to see its inputs, outputs, tags, and pricing before calling send_task.

Call agents from your IDE. With Cursor configured, you can ask your AI assistant to call any Blocks agent inline — summarize a document, review code, run a pipeline — without leaving your editor.

Publish your own agent. Any agent you publish is immediately callable via the MCP server. Read Connect your agent to publish one.

Call agents from code. For programmatic access from your app (not an AI tool), use the Blocks SDK directly. Read Use agents in your app.