MCP Client Specification

​

Protocol Versions

​

SDK Version

​

Supported Protocol Versions

• 2025-06-18 (latest) - Primary support
• 2024-11-05 - Backward compatibility fallback

​

Default Negotiated Version

​

Version Negotiation

1. Client sends initialize request with supported versions
2. Server responds with its supported versions
3. Highest common version is selected
4. All subsequent communication uses negotiated version

​

Capabilities Matrix

​

Tools Capability

• tools/list - Discovery of available tools
• tools/call - Execution of tools with parameters

• Tools are discovered once during initial connection
• Tool schemas are cached for the session lifetime
• No automatic re-discovery (users must disconnect/reconnect for updates)
• See Tool Lifecycle for caching details

​

Transport Layer

​

Supported Transports

​

1. Streamable HTTP (Primary)

• Attempted first on all new connections
• Uses HTTP POST to server endpoint
• Supports streaming responses
• Recommended for all new integrations

POST /mcp HTTP/1.1
Host: example.com
Content-Type: application/json

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

​

2. SSE (Server-Sent Events)

• Automatic fallback if HTTP fails for non-authentication reasons
• Used for backward compatibility
• One-way server-to-client streaming

​

Transport Selection

• Transport is detected once during initial connection
• Selected transport is stored and reused for all future calls
• No per-call transport fallback after initial detection
• Authentication failures prevent fallback to SSE
• Connection failures clear stored transport preference

​

Unsupported Transports

• MCP Inspector - Web-based testing tool
• Claude Desktop - Desktop app with stdio support

​

Server Metadata

​

Required Fields

​

Optional Fields

​

Instructions Field

• Guides Poke’s execution agent on when and how to use your tools
• Acts as the “system prompt” for your integration
• Dramatically impacts agent performance

{
  "name": "github-integration",
  "version": "1.0.0",
  "title": "GitHub Integration",
  "instructions": "Use this integration to manage GitHub repositories, issues, and pull requests. Always search for repositories before creating issues. When creating PRs, fetch the latest branch status first to avoid conflicts. Use list_issues to check existing issues before creating duplicates."
}

​

Connection Lifecycle

​

Initialization Sequence

​

Tool Discovery

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "search_repositories",
        "description": "Search GitHub repositories by query string",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Search query"
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

• Tools are cached in-memory for the connection lifetime
• Cache persists across multiple conversations
• Cache is cleared when user disconnects or connection fails
• No automatic refresh mechanism
• To update tools, users must disconnect and reconnect

​

Tool Execution

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_repositories",
    "arguments": {
      "query": "machine learning"
    }
  },
  "id": 3
}

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 repositories:\n1. tensorflow/tensorflow\n2. pytorch/pytorch\n3. scikit-learn/scikit-learn"
      }
    ]
  }
}

• Called by Poke’s execution agent (not user-facing agents)
• Agent decides when to call tools based on:
  • Tool descriptions
  • Server instructions
  • Conversation context
  • User intent
• Multiple tools can be called in sequence
• Results are passed to user-facing agent for response generation

​

Authentication

​

Supported Methods

​

1. No Auth

• No authentication header sent
• Server must allow unauthenticated access
• User adds integration with URL only

​

2. API Key

• User provides API key during setup
• Poke stores key securely (encrypted at rest)
• Key sent in Authorization header:
  Copy

  Authorization: Bearer <user_api_key>
  

• Validate token on every request
• Return 401 for invalid/expired tokens
• Support key rotation (users can update key in settings)

​

3. OAuth 2.0

• Authorization Code flow with PKCE
• User redirects to your OAuth page
• User authorizes integration
• Poke exchanges code for access token
• Tokens stored securely (encrypted at rest)
• Automatic token refresh using refresh token

• Authorization URL: Where users authorize
• Token URL: For code exchange and refresh
• Supports PKCE (RFC 7636)

Authorization: Bearer <access_token>

• Automatic when access token expires
• Uses refresh token to obtain new access token
• If refresh fails, user must re-authorize

​

Error Handling

​

Standard Error Codes

​

Authentication Errors

• API Key: Prompt user to update key
• OAuth: Attempt token refresh, then prompt re-authorization if refresh fails
• No Auth: Show error (misconfigured server)

• Show “Insufficient permissions” error
• For OAuth: Suggest re-authorization with additional scopes

​

Connection Errors

• Default timeout: 30 seconds
• Show “Connection timeout” error
• Allow retry

• Show “Cannot reach server” error
• Suggest checking server URL and network

• Require valid SSL certificate
• Show certificate error details
• Do not allow insecure connections

​

Rate Limiting

• Return 429 status code with Retry-After header
• Include error message describing limit

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 5,
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Try again in 60 seconds."
  }
}

• Respects Retry-After header
• Shows rate limit message to user
• Prevents further calls until retry time

​

Implementation Checklist

​

Protocol

• Implement protocol version 2025-06-18 or 2024-11-05
• Support version negotiation during initialization
• Handle initialize and initialized messages

​

Transport

• Expose HTTPS endpoint (not HTTP)
• Implement Streamable HTTP transport
• Optionally support SSE for backward compatibility

​

Capabilities

• Respond to tools/list with tool schemas
• Implement tools/call for tool execution
• Return valid JSON-RPC responses

​

Metadata

• Provide name and version in server info
• Optionally provide title for UI display
• Include instructions with guidance for agents

​

Authentication

• Choose authentication pattern (No Auth, API Key, or OAuth)
• Validate credentials on every request
• Return 401 for authentication failures

​

Error Handling

• Return standard JSON-RPC error codes
• Include descriptive error messages
• Implement rate limiting with 429 responses

​

Tools

• Provide clear, descriptive tool names
• Write comprehensive tool descriptions
• Define complete JSON schemas for parameters
• Return structured, informative results

​

Testing Your Integration

​

Local Testing

1. Use MCP Inspector:
   Copy

   npx @modelcontextprotocol/inspector <your-command>
   
   Web-based tool for testing MCP servers
2. Use Claude Desktop:
   • Supports stdio for local testing
   • Test tool discovery and execution
   • Validate server instructions

​

Deployment Testing

1. Deploy to HTTPS endpoint
2. Add integration in Poke:
   • Go to Settings → Integrations
   • Enter your server URL
   • Complete authentication if required
3. Test in conversations:
   • Ask questions that should trigger your tools
   • Verify agent uses tools appropriately
   • Check tool results are accurate

​

Debugging

• Initialization handshake
• Protocol version negotiation
• Tool discovery response
• Authentication success/failure

• Tools not being called: Review server instructions, improve tool descriptions
• Authentication failures: Verify token/OAuth implementation
• Connection timeouts: Check server response time (<30s)
• Transport failures: Ensure HTTPS endpoint is accessible

​

Related Documentation

​

External References

• MCP Official Specification
• MCP TypeScript SDK
• FastMCP Framework
• MCP Inspector