Tools and MCPs

There are two MCP paths in 21st Agents: your own tools now run through the runtime inside the E2B sandbox, while third-party MCP servers are configured with a sibling .mcp.json file next to the agent entrypoint and uploaded during deploy.

Two MCP paths

Your agent tools

Defined in your agent definition
Executed by the runtime process inside the E2B sandbox
Runtime env vars can be used by tools without being exposed as ordinary env vars to the isolated agent process

Third-party MCP servers

Live in a sibling .mcp.json
Loaded during deploy into private runtime config
Support HTTP, SSE, and command-based MCP servers
Use dashboard env vars via placeholders like ${VAR}
Useful for external providers you want Claude Code to call

If one of your tools needs to read or change the active sandbox, do it directly from the tool with local filesystem APIs inside the sandbox runtime. If your own backend service needs to read or change a sandbox, use AgentClient on the Server SDK.

Skills vs external MCP servers

The mechanism is similar, but the file location is different:

Skill

Lives in .claude/skills/<name>/SKILL.md
Contains reusable instructions and reference material
Usually referenced from the system prompt

MCP server

Lives in a sibling .mcp.json next to the agent entrypoint
Contains Claude Code MCP server configuration
Provides an interface for external tools

How deploy-time loading works

During deploy, the CLI reads a sibling .mcp.json file next to your agent entrypoint and uploads it with the agent bundle.

The runtime stores that file privately and generates Claude's MCP config from it. Do not put MCP config at /home/user/workspace/.mcp.json or inside template/.

.mcp.json format

For third-party MCP servers, the file uses Claude Code's standard MCP config format. You can mix remote HTTP servers and command-based local servers in the same file. See Claude's MCP docs for the native format and supported options.

Keep secrets as placeholders here, for example Bearer ${NIA_TOKEN}, and set the real value through dashboard env vars.

Do not hardcode secrets directly in .mcp.json. Use placeholders and agent env vars instead.

.mcp.json

{
  "mcpServers": {
    "nia": {
      "type": "http",
      "url": "https://apigcp.trynia.ai/mcp",
      "headers": {
        "Authorization": "Bearer public-demo-token"
      }
    },
    "svelte": {
      "command": "npx",
      "args": ["-y", "@sveltejs/mcp"]
    }
  }
}

Add the file next to your agent entrypoint

For deployed agents, create a sibling .mcp.json file next to index.ts, index.js, or index.go.

The deploy CLI uploads that file automatically. Do not add it through Sandbox({ files }) or template/.

Sandbox setup still starts from the Sandbox page.

agents/my-agent/index.ts

import { agent } from "@21st-sdk/agent"

export default agent({
  model: "claude-sonnet-4-6",
  systemPrompt: `You are a full-stack coding assistant.
Use the configured MCP servers whenever they are helpful.`,
})

Also create agents/my-agent/.mcp.json with the JSON above. The platform picks up that sibling file during deploy and wires the MCP servers into the runtime automatically.