Skill v1.0.0

currentAutomated scan100/100

cajias/claude-skills/mcp-protocol-server-implementation

──Details

PublishedApril 29, 2026 at 11:33 PM

Content Hashsha256:8dadde64c13c9930...

Git SHAcc0f364908fe

──Files

Files (1 file, 6.6 KB)

SKILL.md6.6 KBactive

SKILL.md · 236 lines · 6.6 KB

name: mcp-protocol-server-implementation description: | Requirements for implementing an MCP (Model Context Protocol) server that works with the official @modelcontextprotocol/sdk client. Use when: (1) implementing an MCP server from scratch, (2) getting "Expected initialize response" errors, (3) MCP client fails to connect or times out, (4) tools/list returns successfully but client doesn't recognize server, (5) implementing MCP Streamable HTTP transport. Covers initialize method, notification handling, SSE response format, and session management. author: Claude Code version: 1.0.0 date: 2026-01-27

MCP Protocol Server Implementation

Problem

When implementing a custom MCP server, the official MCP SDK client (@modelcontextprotocol/sdk) with StreamableHTTPClientTransport fails to connect or times out, even when tools/list returns correct JSON-RPC responses.

Context / Trigger Conditions

Building a custom MCP server (Lambda, Express, etc.) from scratch
Using StreamableHTTPClientTransport from @modelcontextprotocol/sdk
Client throws "Expected initialize response" error
Client times out during connection
Server returns valid JSON-RPC for tools/list but client doesn't work
Direct curl to tools/list works but SDK client fails

Solution

1. Handle the `initialize` Method (REQUIRED)

The SDK client sends initialize as its first request. Your server MUST respond:

typescript

if (method === "initialize") {
  return {
    jsonrpc: "2.0",
    id,
    result: {
      protocolVersion: "2024-11-05", // Current MCP protocol version
      serverInfo: {
        name: "your-server-name",
        version: "1.0.0",
      },
      capabilities: {
        tools: {}, // Indicates server supports tools
      },
    },
  };
}

2. Handle Notifications (REQUIRED)

The client sends notifications/initialized after initialize. Per JSON-RPC 2.0 spec, notifications have NO id field and servers MUST NOT send a response body.

typescript

// Check if message is a notification
function isNotification(message: McpRequest): boolean {
  return message.id === undefined;
}
// In handler:
if (isNotification(mcpRequest)) {
  // Return 202 Accepted with empty body
  return { statusCode: 202, headers, body: "" };
}

3. SSE Response Format (RECOMMENDED)

When client sends Accept: text/event-stream, respond in SSE format:

typescript

function formatAsSSE(response: McpResponse): string {
  return `event: message\ndata: ${JSON.stringify(response)}\n\n`;
}
function clientAcceptsSSE(acceptHeader: string | undefined): boolean {
  return acceptHeader?.includes("text/event-stream") ?? false;
}
// Set Content-Type accordingly
const contentType = useSSE ? "text/event-stream" : "application/json";

4. Session Management (RECOMMENDED)

Track sessions via mcp-session-id header:

typescript

const incomingSessionId = headers["mcp-session-id"];
const sessionId = incomingSessionId ?? randomUUID();
// Include in response headers
responseHeaders["mcp-session-id"] = sessionId;
responseHeaders["Access-Control-Expose-Headers"] = "mcp-session-id";

5. CORS Headers (REQUIRED for browser clients)

typescript

const headers = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Headers":
    "Content-Type,Authorization,mcp-session-id,mcp-protocol-version",
  "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
  "Access-Control-Expose-Headers": "mcp-session-id",
  "Cache-Control": "no-cache",
};

Verification

Test with curl first:

bash

# Test initialize
curl -X POST https://your-server/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"}}}'
 
# Should return protocolVersion, serverInfo, capabilities
 
# Test tools/list
curl -X POST https://your-server/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Then test with MCP SDK client:

typescript

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "test", version: "1.0.0" });
const transport = new StreamableHTTPClientTransport(
  new URL("https://your-server/mcp"),
);
await client.connect(transport);
const tools = await client.listTools();

Example

Complete minimal MCP server handler:

typescript

export function handler(event: APIGatewayProxyEvent): APIGatewayProxyResult {
  const headers = { "Content-Type": "application/json" /* CORS headers */ };
  if (event.httpMethod === "OPTIONS") {
    return { statusCode: 200, headers, body: "" };
  }
  const request = JSON.parse(event.body ?? "{}");
  // Handle notifications (no id = notification)
  if (request.id === undefined) {
    return { statusCode: 202, headers, body: "" };
  }
  // Handle methods
  switch (request.method) {
    case "initialize":
      return {
        statusCode: 200,
        headers,
        body: JSON.stringify({
          jsonrpc: "2.0",
          id: request.id,
          result: {
            protocolVersion: "2024-11-05",
            serverInfo: { name: "my-server", version: "1.0.0" },
            capabilities: { tools: {} },
          },
        }),
      };
    case "tools/list":
      return {
        statusCode: 200,
        headers,
        body: JSON.stringify({
          jsonrpc: "2.0",
          id: request.id,
          result: { tools: MY_TOOLS },
        }),
      };
    case "tools/call":
      // Handle tool execution
      break;
    default:
      return {
        statusCode: 200,
        headers,
        body: JSON.stringify({
          jsonrpc: "2.0",
          id: request.id,
          error: {
            code: -32601,
            message: `Method not found: ${request.method}`,
          },
        }),
      };
  }
}

Notes

Protocol Version: Use 2024-11-05 as of early 2026. Check MCP spec for updates.
JSON-RPC Error Codes:
-32700: Parse error
-32600: Invalid request
-32601: Method not found
-32603: Internal error
Method Call Order: Client always sends initialize first, then notifications/initialized,

then other methods like tools/list.

Timeout Issues: If client times out, check that initialize response is correct—this is

the most common cause.

References

All versions

Skill v1.0.0

MCP Protocol Server Implementation

Problem

Context / Trigger Conditions

Solution

1. Handle the initialize Method (REQUIRED)

2. Handle Notifications (REQUIRED)

3. SSE Response Format (RECOMMENDED)

4. Session Management (RECOMMENDED)

5. CORS Headers (REQUIRED for browser clients)

Verification

Example

Notes

References

1. Handle the `initialize` Method (REQUIRED)