MCP Documentation Service

--- title: MCP Integration Guide description: Guide for integrating with the Model Context Protocol (MCP) author: Claude date: "2023-03-14T00:00:00.000Z" tags: - guide - integration - mcp status: published order: 2 --- # MCP Integration Guide This guide explains how to integrate the MCP Docs Manager with the Model Context Protocol (MCP) client. ## Understanding the MCP Response Format When working with the MCP SDK, it's important to understand how responses are formatted. The MCP SDK follows the JSON-RPC 2.0 specification for request and response formatting. ### Response Structure The MCP response has the following structure: ```json { "result": { "content": [ { "type": "text", "text": "Operation message" } ], "metadata": { // Tool-specific metadata } }, "jsonrpc": "2.0", "id": 123456789 } ``` ### Handling Responses in Your Client When implementing an MCP client, you can extract the result directly from the response: ```javascript // Extract the result from the response if (response.result) { console.log("Result:", JSON.stringify(response.result, null, 2)); } else if (response.error) { console.error("Error:", JSON.stringify(response.error, null, 2)); } else { console.log("Response:", JSON.stringify(response, null, 2)); } ``` ## Server Implementation When implementing an MCP server, ensure your tool handlers return responses in the correct format: ```typescript // Tool handler example in the CallToolRequestSchema handler server.setRequestHandler(CallToolRequestSchema, async (request) => { try { const { name, arguments: args } = request.params; // Validate arguments using zod schema const parsed = ToolSchema.safeParse(args); if (!parsed.success) { throw new Error(`Invalid arguments: ${parsed.error}`); } // Tool implementation return { content: [ { type: "text", text: "Operation completed successfully" } ], metadata: { // Tool-specific metadata } }; } catch (error) { return { content: [ { type: "text", text: `Error: ${error.message}` } ], isError: true }; } }); ``` ## Testing Your Integration You can test your MCP integration using a simple client script with WebSocket: ```javascript import WebSocket from 'ws'; // Connect to the MCP service const socket = new WebSocket('ws://localhost:3000'); socket.on('open', () => { console.log('Connected to MCP service'); // First, list available tools const listToolsRequest = { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} }; console.log('Sending tools/list request'); socket.send(JSON.stringify(listToolsRequest)); }); socket.on('message', (data) => { const response = JSON.parse(data.toString()); console.log('Received response:', JSON.stringify(response, null, 2)); // If we got a successful tools/list response, call a tool if (response.id === 1 && response.result) { const callToolRequest = { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name: "mcp_docs_manager_read_document", arguments: { path: "docs/roadmap.md" } } }; console.log('Sending tools/call request'); socket.send(JSON.stringify(callToolRequest)); } }); socket.on('error', (error) => { console.error('WebSocket error:', error); }); socket.on('close', () => { console.log('Connection closed'); }); ``` Alternatively, you can use stdio for communication: ```javascript import { spawn } from 'child_process'; import readline from 'readline'; // Start the MCP service const service = spawn('node', ['dist/index.js', '--docs-dir', 'docs']); // Create readline interface for reading service output const rl = readline.createInterface({ input: service.stdout, terminal: false }); // Handle service output rl.on('line', (line) => { try { const response = JSON.parse(line); console.log('Received response:', JSON.stringify(response, null, 2)); // If we got a successful response, process it if (response.result) { console.log('Operation successful'); } else if (response.error) { console.error('Error:', response.error); } } catch (error) { console.log('Service message:', line); } }); // Send a request const request = { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "mcp_docs_manager_read_document", arguments: { path: "docs/roadmap.md" } } }; service.stdin.write(JSON.stringify(request) + '\n'); ``` ## Common Issues and Solutions 1. **Method names**: The MCP protocol uses specific method names: `tools/list` for listing available tools and `tools/call` for calling a specific tool. Make sure to use these exact method names. 2. **Tool names**: Tool names follow the format `mcp_docs_manager_*` (e.g., `mcp_docs_manager_read_document`). Make sure to use the correct tool names as returned by the `tools/list` method. 3. **Parameter structure**: When calling a tool, the `arguments` field must be inside the `params` object. For example: `params: { name: "tool_name", arguments: { /* tool arguments */ } }`. 4. **Content format**: The `content` field in the response is always an array of objects with `type` and `text` properties. 5. **Error handling**: Check for the `isError` flag in the response to identify errors, and look for error messages in the `content` field. 6. **Transport options**: The MCP SDK supports both stdio and WebSocket transports. Choose the appropriate transport for your use case. 7. **JSON-RPC format**: All requests and responses follow the JSON-RPC 2.0 specification, including the `jsonrpc`, `id`, `method`, and `params`/`result`/`error` fields. By following these guidelines, you can ensure that your MCP integration works correctly and efficiently.