🐛 Troubleshooting Guide

Searchable solutions to the most common Archestra and MCP errors. Find your issue, understand the cause, and fix it fast.

❌ Unsupported MCP Method Error

Issue #1 • Category: MCP Protocol

🔴 Problem

Error: Unsupported method: tools/list
MCP server does not implement required method

💡 Cause

Your MCP server doesn't implement the tools/list method, which is required for the agent to discover available tools.

✅ Solution

Implement the tools/list handler in your MCP server: 

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "your_tool_name",
        description: "What your tool does",
        inputSchema: {
          type: "object",
          properties: {
            // Your tool parameters
          },
          required: []
        }
      }
    ]
  };
});
💡 Quick Tip: Every MCP server must implement initialize, tools/list, and tools/call at minimum.

⚠️ Streaming Transport Error

Issue #2 • Category: Connection

🔴 Problem

Error: Transport closed unexpectedly
Streaming transport disconnected during tool call

💡 Cause

The MCP server's streaming transport (SSE or WebSocket) closed before completing the request. Common causes:

  • Server crashed or timed out
  • Long-running operation exceeded timeout
  • Network interruption
  • Missing keep-alive headers

✅ Solution

Option 1: Increase timeout for long operations

// In your MCP server configuration
{
  transport: {
    type: "sse",
    timeout: 60000  // 60 seconds
  }
}

Option 2: Add keep-alive mechanism

// Send periodic pings
setInterval(() => {
  transport.send({ type: "ping" });
}, 10000);

🔍 Tool Not Appearing in Agent

Issue #3 • Category: Configuration

🔴 Problem

You created a tool in your MCP server, but the agent can't see or use it.

💡 Cause

Multiple possible causes:

  1. MCP server not registered with the gateway
  2. Tool not returned in tools/list response
  3. Invalid tool schema
  4. Agent not configured to use the MCP server

✅ Solution

Step 1: Verify tool is in tools/list 

curl http://localhost:3000/mcp/tools/list

Step 2: Check gateway configuration 

// gateway.config.json
{
  "mcpServers": [
    {
      "name": "my-server",
      "url": "http://localhost:3000/mcp",
      "enabled": true  // Make sure this is true
    }
  ]
}

Step 3: Restart gateway and agent 

archestra gateway restart
archestra agent restart

🤔 Gateway vs Registry Confusion

Issue #4 • Category: Architecture

🔴 Problem

"Should I connect my MCP server to the gateway or the registry?"

💡 Explanation

🌉 Gateway

Purpose: Routes tool calls from agents to MCP servers

When to use: Production deployments, multiple agents

URL format: http://gateway:8080

📚 Registry

Purpose: Discovers and lists available MCP servers

When to use: Development, testing, server discovery

URL format: http://registry:9090

✅ Solution

✅ Simple Rule: In development, connect your agent directly to MCP servers. In production, use the Gateway to route traffic.

📡 JSON-RPC Format Errors

Issue #5 • Category: Protocol

🔴 Problem

Error: Invalid JSON-RPC request
Missing 'jsonrpc' field or invalid format

💡 Cause

MCP uses JSON-RPC 2.0 format. Your request is missing required fields or has incorrect structure.

✅ Solution

Use the correct JSON-RPC format:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1"
    }
  },
  "id": 1
}
⚠️ Common Mistake: Forgetting the "jsonrpc": "2.0" field or using wrong id type (must be string or number).

🔗 /mcp Endpoint 404 Error

Issue #6 • Category: Routing

🔴 Problem

Error: 404 Not Found
GET http://localhost:3000/mcp

💡 Cause

Your MCP server doesn't expose the /mcp endpoint, or it's on a different path.

✅ Solution

Ensure your server has the MCP endpoint properly configured: 

// Express example
app.use('/mcp', mcpRouter);

// Or with SSE transport
const transport = new SSEServerTransport('/mcp', res);
server.connect(transport);

Test the endpoint:

curl http://localhost:3000/mcp/sse
# Should return a streaming connection

📨 Accept Header Issues

Issue #7 • Category: HTTP

🔴 Problem

Error: 406 Not Acceptable
Server requires 'Accept: text/event-stream' header

💡 Cause

SSE-based MCP servers require the correct Accept header for streaming responses.

✅ Solution

Include the correct headers when connecting:

const client = new Client({
  name: "my-agent",
  version: "1.0.0"
}, {
  capabilities: {}
});

const transport = new SSEClientTransport(
  new URL("http://localhost:3000/mcp/sse"),
  {
    headers: {
      'Accept': 'text/event-stream'
    }
  }
);

await client.connect(transport);

🛠️ SDK vs Manual MCP Implementation

Issue #8 • Category: Development

🔴 Problem

"Should I use the MCP SDK or implement the protocol manually?"

💡 Recommendation

✅ Use the SDK (Recommended)

  • Handles JSON-RPC automatically
  • Type-safe with TypeScript
  • Built-in error handling
  • Transport abstraction
  • Well-tested and maintained

⚠️ Manual Implementation

  • More control over behavior
  • Smaller bundle size
  • Language flexibility
  • Learning opportunity
  • More debugging needed

✅ Solution

For beginners, start with the SDK:

npm install @modelcontextprotocol/sdk

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

📋 Quick Debug Checklist

Still Stuck? 🆘

Join our community or check the official docs

GitHub Issues Architecture Docs