Adding MCP Backends

Adding MCP Backends

This guide walks through connecting MCP (Model Context Protocol) servers to AgentCTX as tool backends. Once connected, agents can discover and call tools through the CTX language.

Overview

Agent → ?t github → Gateway → MCP Backend (GitHub server) → Tool Results

AgentCTX doesn’t run tools directly. It delegates to MCP-compatible servers and manages scoping, authorization, and caching.

Step 1: Register a Backend

actx add github \
  --command "npx -y @modelcontextprotocol/server-github" \
  --roles "code,issues" \
  --transport stdio

This adds an entry to .context/actx.yaml:

backends:
  - id: github
    cmd: "npx -y @modelcontextprotocol/server-github"
    roles:
      - code
      - issues
    transport: stdio

Step 2: Configure Roles

Roles control which agents can see which tools. An agent must have a matching role to access a backend’s tools.

backends:
  - id: admin-tools
    roles: [admin]         # Only admin agents
  - id: dev-tools
    roles: [code, issues]  # Dev and PM agents
  - id: public-tools
    roles: [default]       # All agents

Step 3: Choose a Transport

Transport	When to Use
stdio	Local MCP servers (npx, python scripts)
sse	Remote servers with HTTP endpoints
http	REST-based MCP adapters

# Local server via stdio
actx add filesystem --command "npx -y @modelcontextprotocol/server-filesystem ." --transport stdio

# Remote server via SSE
actx add remote-api --command "node api-server.js" --transport sse

Step 4: Verify

Start the gateway and search for tools:

actx start --transport sse --port 3100

# In another terminal
actx query '?t github'

You should see the tools from your registered backend in the results.

Lazy Spawning

Backends are lazy-spawned by default:

• The MCP server process doesn’t start until the first tool query
• This keeps gateway startup fast
• Unused backends consume zero resources

To change this behavior, set lazy: false in actx.yaml:

backends:
  - id: always-on
    cmd: "node critical-server.js"
    roles: [monitoring]
    transport: stdio
    lazy: false

Tool Namespacing

All tools are automatically namespaced under their backend ID:

Backend ID	MCP Tool Name	CTX Name
github	issues.create	github.issues.create
filesystem	read_file	filesystem.read_file
godot	assets.decimate_mesh	godot.assets.decimate_mesh

Popular MCP Servers

Server	Install Command	Roles
GitHub	npx -y @modelcontextprotocol/server-github	code, issues
Filesystem	npx -y @modelcontextprotocol/server-filesystem .	files
PostgreSQL	npx -y @modelcontextprotocol/server-postgres	database
Puppeteer	npx -y @modelcontextprotocol/server-puppeteer	browser

See Also

• actx add — CLI reference
• Gateway & Routing — how backends are managed