MCP Integration

MCP (Model Context Protocol) is the Tools layer in AgentShip’s four pluggable architecture layers. Declare servers in YAML — AgentShip connects, discovers tools, and injects LLM-ready documentation into the system prompt automatically. Works with both ADK and LangGraph engines, no code changes needed.

Transports

Transport

Use case

Auth

stdio

Local servers (npx, Python scripts)

Env vars

http / sse

Remote APIs (GitHub, Slack, etc.)

OAuth 2.0

Configuration

1. Define servers in .mcp.settings.json

{
  "servers": {
    "postgres": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${AGENT_SESSION_STORE_URI}"
      ]
    },
    "github": {
      "transport": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "auth": {
        "type": "oauth",
        "provider": "github",
        "client_id_env": "GITHUB_OAUTH_CLIENT_ID",
        "client_secret_env": "GITHUB_OAUTH_CLIENT_SECRET",
        "authorize_url": "https://github.com/login/oauth/authorize",
        "token_url": "https://github.com/login/oauth/access_token",
        "scopes": ["repo", "read:org"]
      }
    },
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

${VAR} tokens in args are resolved from the environment at startup.

2. Reference servers in your agent YAML

agent_name: database_agent
execution_engine: adk   # or langgraph — both work

mcp:
  servers:
    - postgres   # STDIO: shared client across agents
    - github     # HTTP/OAuth: per-agent client

That’s it. AgentShip automatically:

  • Connects to each MCP server

  • Discovers available tools

  • Generates documentation for the LLM

  • Injects it into the system prompt

How It Works

.mcp.settings.json
    ↓
MCPServerRegistry (loads + resolves env vars)
    ↓
MCPClientManager (one client per server, or per agent for OAuth)
    ↓
StdioMCPClient / SSEMCPClient
    ↓
Tool Discovery → LLM-friendly documentation → System prompt

STDIO Servers (Local)

STDIO servers run as local subprocesses via npx or Python. They start when the agent initialises and reconnect automatically if the event loop changes (normal in production ASGI servers).

Example: PostgreSQL agent

agent_name: postgres_agent
execution_engine: adk
instruction_template: |
  You are a database assistant. Use the available tools to query and analyse data.

mcp:
  servers:
    - postgres

{
  "servers": {
    "postgres": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${AGENT_SESSION_STORE_URI}"]
    }
  }
}

HTTP/OAuth Servers (Remote)

HTTP/SSE servers connect to remote APIs using OAuth 2.0. Each agent gets its own client to prevent token cross-contamination.

Requirements: Set AGENTSHIP_AUTH_DB_URI in your .env — this is where OAuth tokens are stored (encrypted with Fernet).

Connect a user

pipenv run agentship mcp connect github --user-id alice
# Opens browser → GitHub OAuth → token stored automatically

pipenv run agentship mcp list-connections --user-id alice
pipenv run agentship mcp disconnect github --user-id alice

Example: GitHub agent

See src/all_agents/github_adk_mcp_agent/ and src/all_agents/github_langgraph_mcp_agent/ for complete working examples.

Auto Tool Documentation

Tools discovered from MCP servers are automatically documented and injected into the agent’s system prompt. No manual work needed.

Given this MCP tool schema:

{
  "name": "query",
  "description": "Execute a read-only SQL query",
  "inputSchema": {
    "properties": {
      "sql": {"type": "string", "description": "SQL to run"}
    },
    "required": ["sql"]
  }
}

AgentShip generates and injects:

## Available Tools

### query
Execute a read-only SQL query

Parameters:
- sql (string, required): SQL to run

Example: {"sql": "SELECT * FROM users LIMIT 10"}

Client Isolation

STDIO clients are shared across agents (safe — no auth state). OAuth clients are isolated per agent:

  • STDIO cache key: "{server_id}"

  • OAuth cache key: "{server_id}:{agent_name}"

This ensures users of one agent can’t access tokens belonging to another.

Troubleshooting

“Event loop changed, reconnecting…” — Normal in production. STDIO clients auto-reconnect on each request.

ValueError: AGENTSHIP_AUTH_DB_URI — Required for HTTP/OAuth servers. Add to .env.

Tools not appearing — Check that the server name in YAML matches the key in .mcp.settings.json.

npx not found — Install Node.js: brew install node (macOS) or see nodejs.org.