Skip to main content

MCP Transport Integration

This guide explains how to enable and use the MCP (Model Context Protocol) transport endpoint in AgentVisor, allowing MCP clients like Claude Desktop and Cursor to interact with your agents as tools.

Overview​

The MCP transport exposes AgentVisor agents as MCP tools via the /mcp endpoint. This enables:

  • Claude Desktop integration: Access your agents directly from Claude
  • Cursor integration: Use agents as coding assistants
  • Any MCP client: Standard protocol for AI tool access
Understanding MCP in AgentVisor

This guide covers the MCP Transport - exposing your agents as MCP tools to external clients. For agents accessing external MCP servers, see MCP Gateway.

PatternDirectionPurpose
MCP Transport (this guide)External MCP clients → AgentVisor agentsClaude Desktop, Cursor call your agents
MCP GatewayAgentVisor agents → External MCP serversYour agents use GitHub, Slack, etc.

For a complete overview of AgentVisor's transport architecture, see API Transports.

Enabling the MCP Transport​

Configuration​

Enable the MCP transport in your agentvisor.yaml:

api:
  listen_addr: ":8090"
  
  openapi:
    enabled: true   # OpenAPI/REST (keep enabled for full functionality)
  mcp:
    enabled: true   # Enable MCP transport at /mcp

Or via environment variable:

export AGENTVISOR_API_MCP_ENABLED=true

Verifying the Transport​

Once enabled, the MCP endpoint is available at:

http://localhost:8090/mcp

You can verify it's working using curl:

# Send an MCP initialize request
curl -X POST http://localhost:8090/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0.0"}
    }
  }'

Connecting from Claude Desktop​

Step 1: Configure Claude Desktop​

Add AgentVisor to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agentvisor": {
      "url": "http://localhost:8090/mcp"
    }
  }
}

Step 2: Restart Claude Desktop​

After updating the configuration, restart Claude Desktop to pick up the changes.

Step 3: Verify Connection​

In Claude Desktop, you should see your AgentVisor agents listed as available tools. Claude can now invoke your agents directly during conversations.

Connecting from Cursor​

Step 1: Configure Cursor​

Add AgentVisor to your Cursor MCP configuration:

Settings → Features → MCP Servers → Add Server

{
  "name": "agentvisor",
  "url": "http://localhost:8090/mcp"
}

Step 2: Use in Chat​

Once connected, Cursor can use your AgentVisor agents when you ask it to perform tasks that match your agent's capabilities.

How Agents Are Exposed​

Tool Discovery​

When an MCP client calls tools/list, AgentVisor returns tools from six independently gateable categories, each toggled via api.mcp.tools.<category> (all enabled by default):

CategoryConfig KeyTools
Agentsapi.mcp.tools.agentsOne tool per registered agent (invokes the agent)
Systemapi.mcp.tools.systemhealth_check, list_agents
Threadsapi.mcp.tools.threadscreate_thread, get_thread, update_thread, delete_thread, search_threads, copy_thread
Runsapi.mcp.tools.runsget_run, list_runs, cancel_run, wait_for_run
Stateapi.mcp.tools.stateget_thread_state, update_thread_state, get_thread_history
Storeapi.mcp.tools.storestore_put, store_get, store_delete, store_search, store_list_namespaces

For the Agents category, each registered agent becomes a tool:

Agent PropertyMCP Tool Field
Agent name (from langgraph.json)Tool name
Agent descriptionTool description
Agent input schemaTool input schema

Tool Invocation​

When a client calls tools/call on an agent tool, AgentVisor:

  1. Creates a new thread (or uses an existing one if specified)
  2. Creates a run with the provided input
  3. Waits for completion (similar to POST /runs/wait)
  4. Returns the agent's output

Tools in the other five categories map directly onto the corresponding REST/gRPC operation (e.g. create_thread calls the same thread-creation logic as POST /threads).

Resources (Optional)​

Depending on configuration, MCP resources may expose:

  • Thread state as browsable resources
  • Checkpoint data for debugging
  • Store items (if store provider is enabled)

Authentication​

No Authentication​

For local development, you can run without authentication:

api:
  auth:
    enabled: false
  mcp:
    enabled: true

OIDC Authentication​

For production, enable authentication:

api:
  auth:
    enabled: true
    oidc_issuer: "https://auth.example.com"
    oidc_audience: "agentvisor"
  mcp:
    enabled: true

MCP clients must then include a bearer token in requests:

curl -X POST http://localhost:8090/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '...'

Configure Claude Desktop with authentication:

{
  "mcpServers": {
    "agentvisor": {
      "url": "http://localhost:8090/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

TLS Configuration​

For HTTPS endpoints:

api:
  listen_addr: ":8090"
  tls:
    enabled: true
    cert_file: "/path/to/server.crt"
    key_file: "/path/to/server.key"
  mcp:
    enabled: true

Update client configuration to use HTTPS:

{
  "mcpServers": {
    "agentvisor": {
      "url": "https://agentvisor.example.com:8090/mcp"
    }
  }
}

Troubleshooting​

MCP endpoint not responding​

  1. Verify the transport is enabled:

    grep -A2 "mcp:" agentvisor.yaml

  2. Check server logs for errors:

    docker logs agentvisor-host | grep -i mcp

  3. Ensure the server is running and accessible:

    curl http://localhost:8090/health

Claude Desktop not showing agents​

  1. Check the configuration file path is correct for your OS
  2. Verify JSON syntax in the config file
  3. Restart Claude Desktop completely
  4. Check Claude Desktop logs for connection errors

Authentication errors​

  1. Verify the token is valid and not expired
  2. Check that the audience matches your configuration
  3. Ensure the OIDC issuer is reachable from AgentVisor

See Also​