MCP server fails to handle tools/list, resources/list, prompts/list after successful initialization

[alebedev80]

MCP server not handling standard protocol methods (tools/list, resources/list, prompts/list)

Description

When using mcp-golang to create an HTTP MCP server, the library successfully handles the initialize and notifications/initialized methods, but fails to respond to standard MCP protocol methods like tools/list, resources/list, and prompts/list. This causes Claude AI and other MCP clients to timeout when trying to discover available tools.

Environment

• Library version: Latest from main branch
• Go version: 1.21+
• Transport: HTTP transport (http.NewHTTPTransport)
• Client: Claude AI MCP integration
• Server: Ubuntu/Linux with nginx reverse proxy

Expected Behavior

After successful initialization, the MCP server should automatically respond to:

• tools/list - Return list of registered tools
• resources/list - Return available resources (empty array if none)
• prompts/list - Return available prompts (empty array if none)

Actual Behavior

1. ✅ initialize request succeeds
2. ✅ notifications/initialized succeeds
3. ❌ tools/list request never reaches the application (times out on client side)
4. ❌ resources/list request never reaches the application
5. ❌ prompts/list request never reaches the application

Code to Reproduce

package main

import (
    "log"
    "time"
    mcp_golang "github.com/metoro-io/mcp-golang"
    "github.com/metoro-io/mcp-golang/transport/http"
)

type TimeArgs struct {
    Format string `json:"format" jsonschema:"description=The time format to use"`
}

func main() {
    transport := http.NewHTTPTransport("/").WithAddr("127.0.0.1:8888")
    
    server := mcp_golang.NewServer(
        transport,
        mcp_golang.WithName("test-server"),
        mcp_golang.WithInstructions("Test MCP server"),
        mcp_golang.WithVersion("0.0.1"),
    )

    err := server.RegisterTool("time", "Returns current time", func(args TimeArgs) (*mcp_golang.ToolResponse, error) {
        format := args.Format
        if format == "" {
            format = "2006-01-02 15:04:05"
        }
        return mcp_golang.NewToolResponse(mcp_golang.NewTextContent(time.Now().Format(format))), nil
    })
    if err != nil {
        panic(err)
    }

    log.Printf("Starting server...")
    err = server.Serve()
    if err != nil {
        panic(err)
    }
}

Server Logs

2025/06/20 11:07:12 Received POST request from 127.0.0.1:47366
2025/06/20 11:07:12 Request: map[id:0 jsonrpc:2.0 method:initialize params:map[...]]
2025/06/20 11:07:12 Received POST request from 127.0.0.1:47384  
2025/06/20 11:07:12 Request: map[jsonrpc:2.0 method:notifications/initialized]
# No tools/list, resources/list, or prompts/list requests appear in logs

Client Logs (Claude AI)

2025-06-20 12:45:41 [error] Request tools/list to MCP server failed: Error: MCP error -32001: Request timed out
2025-06-20 12:45:55 [error] Request resources/list to MCP server failed: Error: MCP error -32000: Connection closed
2025-06-20 12:45:58 [error] Request prompts/list to MCP server failed: Error: MCP error -32001: Request timed out

Investigation Results

1. Network level: nginx access logs show only initialize POST requests receiving 200 responses, but tools/list requests result in 504 Gateway Timeout
2. Protocol compliance: The MCP Inspector tool can successfully connect and list tools from the same server endpoint
3. Manual implementation: A manual HTTP handler correctly responds to all MCP methods when implemented from scratch

Suspected Root Cause

The mcp-golang library appears to:

1. Successfully handle the initialization handshake
2. Not automatically register handlers for standard MCP protocol methods (tools/list, resources/list, prompts/list)
3. Not provide a way to manually register these handlers

Possible Solutions

1. Auto-registration: The library should automatically handle tools/list and return registered tools
2. Manual registration: Provide methods like server.RegisterMethodHandler("tools/list", handler)
3. Documentation: Clarify if additional setup is required for standard protocol methods

Workaround

Currently using a manual HTTP handler implementation that properly responds to all MCP protocol methods.

Nginx Configuration

The server is deployed behind nginx with the following configuration:

server {
    listen 80;
    server_name mcp.example.com;
    location / {
        return 301 https://mcp.example.com$request_uri;
    }
}

server {
    listen 443 ssl http2;
    server_name mcp.example.com;
...
    
    location / {
        # Proxy to Go MCP server
        proxy_pass http://127.0.0.1:8888;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # MCP-specific optimizations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
        
        # JSON payload handling
        proxy_buffering off;
        client_max_body_size 1M;
        proxy_set_header Connection "keep-alive";
    }
}

Nginx Access Logs

34.162.46.92 - - [20/Jun/2025:11:07:12 +0200] "POST /?api_key=test_key&sender=claude1 HTTP/1.1" 200 334 "-" "python-httpx/0.27.0" "-"
34.162.46.92 - - [20/Jun/2025:11:07:12 +0200] "POST /?api_key=test_key&sender=claude1 HTTP/1.1" 200 0 "-" "python-httpx/0.27.0" "-"
34.162.46.92 - - [20/Jun/2025:11:07:13 +0200] "GET /?api_key=test_key&sender=claude1 HTTP/1.1" 405 19 "-" "python-httpx/0.27.0" "-"

Shows successful POST requests for initialization, but subsequent requests either timeout (504) or result in method not allowed (405) for GET requests.

Additional Context

• MCP Protocol Version: 2024-11-05
• The same server setup works correctly with MCP Inspector but fails with Claude AI
• Client makes requests with User-Agent: python-httpx/0.27.0
• Network connectivity is confirmed (initialization succeeds)
• This suggests the library may not be fully implementing the MCP specification

Would appreciate guidance on whether this is a missing feature, bug, or configuration issue. Happy to provide additional debugging information or test fixes.