​

MCP Protocol 2025-03-26 Compliance

​

📋 Context & Objective

1. Navigate to Claude Settings > Connectors
2. Click “Add custom connector”
3. Enter your server’s discovery URL: https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/.well-known/mcp-server
4. Optionally configure OAuth credentials
5. Authenticate and enable tools
6. Use your tools in Claude conversations

​

✅ Implementation Status: COMPLIANT

​

Discovery Endpoint ✅

• Format: Returns PLAIN JSON (not JSON-RPC wrapped) per specification
• URL: /.well-known/mcp-server
• Content: Server metadata, capabilities, single /messages endpoint, authentication
• Optimization: Discovery focuses on /messages as primary endpoint for Claude Connectors

​

Streamable HTTP Transport ✅

• Primary Endpoint: /messages - Single endpoint for all JSON-RPC communication
• Base URL Support: / - Also accepts JSON-RPC requests (mcp-remote compatibility)
• Supported Methods: POST (JSON-RPC requests), GET (discovery/SSE streaming)
• Protocol Compliance: Both /messages and / handle JSON-RPC identically
• Authentication Note: Base URL (mcp-router) is publicly accessible (verify_jwt = false), but individual deployments enforce authentication based on their mcp_auth_method setting
• Utility Endpoints: /health, /docs available but not part of MCP discovery

​

JSON-RPC Methods Supported ✅

• initialize - Session initialization
• tools/list - List available tools
• tools/call - Execute a tool

​

Authentication ✅

• OAuth 2.1 with PKCE support
• JWT Bearer token support
• Public (no-auth) mode available
• Configurable per deployment

​

📊 Compliance Checklist

​

Discovery & Configuration ✅

• /.well-known/mcp-server returns valid, spec-compliant PLAIN JSON
• Discovery focuses on single /messages endpoint (MCP best practice)
• Base URL (/) accepts JSON-RPC for mcp-remote compatibility
• Server metadata includes all required fields with tool count
• Endpoint URLs are complete HTTPS URLs
• Authentication configuration is correct for deployment type
• OAuth metadata endpoint exists (for OAuth deployments)
• Utility endpoints in _meta for monitoring (not part of MCP discovery)

​

Transport Implementation ✅

• Single /messages endpoint implements Streamable HTTP
• POST method handles JSON-RPC messages
• GET method supports SSE streaming
• Legacy endpoints maintained for compatibility
• Proper CORS headers

​

Protocol Compliance ✅

• JSON-RPC 2.0 format used correctly
• Request IDs preserved in responses
• Error codes match specification (-32600, -32601, -32602, -32700)
• Required methods implemented (initialize, tools/list, tools/call)

​

Tool Functionality ✅

• Tools discovered via tools/list
• Tool metadata complete (name, description, inputSchema)
• Tools invoked via tools/call
• Parameters validated
• Results in MCP content format
• OpenAPI → Tool conversion working
• API calls execute successfully

​

🧪 Test Validation Results

​

✅ Discovery Endpoint Tests (CRITICAL)

​

✅ Messages Endpoint Tests

​

✅ Initialize Method

{
  "jsonrpc": "2.0",
  "id": "<preserved>",
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {},
      "logging": {}
    },
    "serverInfo": {
      "name": "{slug}-mcp-server",
      "version": "0.1.0"
    }
  }
}

​

✅ Tools List Method

• ✅ Iterates through all OpenAPI paths
• ✅ Extracts GET, POST, PUT, PATCH, DELETE operations
• ✅ Generates tool names from operationId or path+method
• ✅ Builds input schemas from parameters and request body
• ✅ Marks required fields appropriately
• ✅ Comprehensive error handling (returns partial results on error)

​

✅ Tools Call Method

1. ✅ Validates tool name exists
2. ✅ Finds endpoint in OpenAPI spec
3. ✅ Constructs target API URL
4. ✅ Injects authentication (Bearer, API Key, Basic)
5. ✅ Handles path, query, header, body parameters
6. ✅ Makes HTTP request to target service
7. ✅ Returns response in MCP content format

​

✅ Error Handling

{
  "jsonrpc": "2.0",
  "id": "<preserved or null>",
  "error": {
    "code": -32601,
    "message": "Method not found: unknown_method",
    "data": {
      "supported_methods": ["initialize", "tools/list", "tools/call"]
    }
  }
}

​

✅ CORS Configuration

​

✅ Production Readiness

​

🔧 Critical Fixes Applied

​

1. Discovery Endpoint Access (CRITICAL)

• Moved discovery check before authentication
• Returns early with public response
• Clients can now discover auth requirements before authenticating

​

2. Tool Extraction Error Handling (CRITICAL)

• Added validation for spec structure
• Safe null/undefined checks
• Try-catch with graceful degradation
• Returns empty array on error (server still works)

​

3. Console Output Contamination (CRITICAL)

• All logs prefixed with [INTERNAL] or similar
• console.error for errors (goes to stderr)
• No output between response creation and return

​

4. JSON Response Purity (CRITICAL)

• No console output before response
• Clean JSON.stringify(metadata, null, 2)
• No trailing newlines
• Proper Content-Type: application/json; charset=utf-8

​

🔑 Key Architecture Decisions

​

Why Single /messages Endpoint?

• Server MUST provide ONE endpoint for all JSON-RPC communication
• Simplifies client implementation
• Enables efficient streaming via SSE
• Standard approach for remote MCP servers

​

Why Plain JSON for Discovery?

• Discovery endpoint is NOT part of JSON-RPC communication
• It’s a metadata endpoint queried before establishing connection
• Must be parseable without JSON-RPC knowledge
• Matches all reference implementations

​

Discovery Optimization for Claude Connectors

• Discovery returns single /messages endpoint per MCP spec
• Claude Connectors only need /messages to function
• Utility endpoints (/health, /docs) available but in _meta section
• Legacy /tool endpoint remains functional but not advertised
• Clean, focused discovery response for better client compatibility

​

📚 API Reference

​

Discovery Endpoint

GET /.well-known/mcp-server

{
  "protocol_version": "2025-03-26",
  "server_info": {
    "name": "example-mcp-server",
    "version": "0.1.0",
    "description": "MCP server for Example API - 23 tools available"
  },
  "capabilities": {
    "tools": true,
    "resources": false,
    "prompts": false
  },
  "endpoints": {
    "messages": "https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/example/messages"
  },
  "authentication": {
    "required": false,
    "methods": [],
    "description": "No authentication required - public access"
  },
  "_meta": {
    "health": "https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/example/health",
    "docs": "https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/example/docs",
    "tool_count": 23,
    "api_base": "https://api.example.com"
  }
}

​

Messages Endpoint (Primary)

POST /messages
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

​

SSE Streaming (Optional)

GET /messages
Accept: text/event-stream

​

Base URL Endpoint (mcp-remote compatibility)

POST /
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [...]
  }
}

• ✅ JSON-RPC requests (with jsonrpc: "2.0" and method field) → Routed to /messages handler
• ✅ Non-JSON-RPC POST requests → Returns discovery metadata
• ✅ GET requests → Returns discovery metadata (unchanged)
• ✅ All JSON-RPC methods supported: initialize, tools/list, tools/call

​

🧪 Testing & Integration

​

Testing with Claude

​

Add Connector

1. Go to Claude Settings > Connectors
2. Click “Add custom connector”
3. Enter URL: https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{your-slug}/.well-known/mcp-server
4. Configure OAuth (if required)
5. Click “Add”

​

Enable Tools

1. Start a chat in Claude
2. Click “Search and tools” (lower left)
3. Find your connector
4. Enable specific tools
5. Use tools in conversation

​

Step-by-Step Claude.ai Integration

1. Open Claude.ai
   • Go to https://claude.ai
   • Log in to your account
2. Navigate to Connectors
   • Click Settings (gear icon)
   • Select “Connectors” from the menu
3. Add Custom Connector
   • Click “Add custom connector”
   • Enter discovery URL: https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{your-slug}/.well-known/mcp-server
4. Complete Authentication (if required)
   • For OAuth: Follow OAuth flow
   • For JWT: Enter Bearer token
   • For public (none): No auth needed
5. Enable Tools
   • Review available tools
   • Toggle on/off as needed
   • Click “Save”
6. Start Using
   • Tools are now available in conversations
   • Claude can invoke them automatically
   • Monitor usage in dashboard

​

Test Execution

./claude-connector-test.sh https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{your-slug}

• Total Tests: 45
• Passed: 45
• Failed: 0
• Pass Rate: 100.0%
• Status: ✓ ALL TESTS PASSED

​

Quick Validation Commands

# Test discovery endpoint
curl -s https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/.well-known/mcp-server | jq .

# Test initialize
curl -X POST https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"test","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{}}}' | jq .

# Test tools/list
curl -X POST https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"test","method":"tools/list","params":{}}' | jq .

​

Common Troubleshooting

• ✅ Check OpenAPI spec is valid
• ✅ Verify tools/list returns tools array
• ✅ Check authentication is configured correctly

• ✅ Verify target API credentials
• ✅ Check API base URL is correct
• ✅ Review parameter mapping

• ✅ Verify JWT token or OAuth setup
• ✅ Check token expiration
• ✅ Validate token in database

• ✅ Verify discovery endpoint is publicly accessible
• ✅ Check JSON format is valid (not JSON-RPC wrapped)
• ✅ Ensure HTTPS is enforced

​

🔒 Security Measures

​

Implemented Security Features

1. Row Level Security (RLS)
   • All database tables protected
   • Users can only access their own data
2. Rate Limiting
   • Enforced via Supabase stored procedures
   • Hourly and monthly limits
3. Authentication Options
   • OAuth 2.1 with PKCE
   • JWT Bearer tokens
   • Public access (configurable)
4. No Code Execution
   • Server only routes to target APIs
   • No user code is ever executed
   • OpenAPI specs stored securely
5. Input Validation
   • JSON-RPC validation
   • Parameter type checking
   • Tool name validation

​

OAuth 2.1 Requirements

• ✅ PKCE required (S256 only, plain not supported)
• ✅ State parameter for CSRF protection
• ✅ Redirect URI exact matching (no wildcards)
• ✅ HTTPS required (except localhost)
• ✅ Rate limiting: 20/hour authorize, 10/min token, 20/hour register

​

Token Security

• ✅ Access tokens: 1-hour expiration
• ✅ Format: mcp_access_{uuid}
• ✅ Revocation via revoked flag in database
• ✅ Validation on every request
• ✅ One-time use authorization codes

​

⚡ Performance Characteristics

​

Expected Response Times

​

Optimization Notes

• ✅ Discovery endpoint caching (Cache-Control: no-store intentional for fresh auth info)
• ✅ Tool definitions extracted once per request
• ✅ Database queries optimized with proper indexing
• ✅ No unnecessary external API calls

​

📊 Monitoring & Debugging

​

Edge Function Logs

• Look for [MCP-Auth] Authentication events
• Look for [INTERNAL] Internal processing logs
• Look for [ERROR-*] Error events with UUIDs

-- View recent MCP router invocations
SELECT * FROM edge_function_logs
WHERE function_name = 'mcp-router'
ORDER BY timestamp DESC
LIMIT 50;

-- Find errors
SELECT * FROM edge_function_logs
WHERE function_name = 'mcp-router'
  AND level = 'error'
ORDER BY timestamp DESC;

​

🔍 Verification Tests

​

1. Metadata Discovery

curl https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/.well-known/mcp-server

​

2. Protocol Headers

curl -I https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/tool \
  -H "Authorization: Bearer {token}"

​

3. Authentication

# Without token - should return 401
curl https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/tool

# With OAuth token - should return 200
curl -H "Authorization: Bearer mcp_access_xxxxx" \
  https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/tool

# With JWT token - should return 200
curl -H "Authorization: Bearer {jwt-token}" \
  https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-router/{slug}/tool

​

4. OAuth Discovery

curl https://nqfciqtsrcjorlqcglmq.supabase.co/functions/v1/mcp-oauth-server/.well-known/oauth-authorization-server

​

OAuth Metadata Response

{
  "issuer": "https://nqfciqtsrcjorlqcglmq.supabase.co",
  "authorization_endpoint": "https://.../authorize",
  "token_endpoint": "https://.../token",
  "registration_endpoint": "https://.../register",
  "scopes_supported": ["openid", "email", "profile"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post"]
}

​

📖 References

• MCP Protocol Specification
• Claude Custom Connectors
• OAuth 2.1 Specification
• RFC 7591 - Dynamic Client Registration
• RFC 7636 - PKCE
• RFC 8414 - OAuth Authorization Server Metadata
• JSON-RPC 2.0 Specification
• Supabase Edge Functions

​

🎯 Success Criteria

​

🚀 Status & Next Steps

• MCP Protocol Specification 2025-03-26
• MCP Streamable HTTP Transport
• Claude Custom Connector Requirements
• JSON-RPC 2.0 Specification

1. Test Discovery: Verify plain JSON response
   Copy

   curl https://.../mcp-router/{slug}/.well-known/mcp-server | jq '.'
   

2. Test Messages Endpoint: Send JSON-RPC request
   Copy

   curl -X POST https://.../mcp-router/{slug}/messages \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
   

3. Add to Claude: Use discovery URL in Claude Settings > Connectors
4. Test Tool Execution: Enable tools and use in conversation
5. Monitor Usage: Check logs and handle errors appropriately