MCP Development

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to interact with external tools, data sources, and services in a standardized way.

Core Concepts

Concept	Description
Tools	Functions the AI can call
Resources	Data the AI can read
Prompts	Pre-defined prompt templates
Transports	Communication methods (stdio, HTTP)

MCP Server Structure

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0",
}, {
  capabilities: {
    tools: {},
    resources: {},
  }
});

// Define tools
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_data",
      description: "Fetch data from the API",
      inputSchema: {
        type: "object",
        properties: {
          id: { type: "string", description: "Item ID" }
        },
        required: ["id"]
      }
    }
  ]
}));

// Handle tool calls
server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;
  
  if (name === "get_data") {
    const result = await fetchData(args.id);
    return { content: [{ type: "text", text: JSON.stringify(result) }] };
  }
  
  throw new Error(`Unknown tool: ${name}`);
});

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);

Tool Design Best Practices

Clear Descriptions

{
  name: "search_documents",
  description: "Search documents by keyword. Returns matching documents with relevance scores. Use when the user asks to find or search for specific content.",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Search query - can include multiple keywords"
      },
      limit: {
        type: "integer",
        description: "Maximum number of results (default: 10)",
        default: 10
      }
    },
    required: ["query"]
  }
}

Error Handling

server.setRequestHandler("tools/call", async (request) => {
  try {
    const result = await executeTool(request.params);
    return { content: [{ type: "text", text: result }] };
  } catch (error) {
    return {
      content: [{
        type: "text",
        text: `Error: ${error.message}`
      }],
      isError: true
    };
  }
});

Resources

server.setRequestHandler("resources/list", async () => ({
  resources: [
    {
      uri: "file:///docs/readme.md",
      name: "README",
      description: "Project documentation",
      mimeType: "text/markdown"
    }
  ]
}));

server.setRequestHandler("resources/read", async (request) => {
  const { uri } = request.params;
  const content = await readResource(uri);
  return {
    contents: [{
      uri,
      mimeType: "text/markdown",
      text: content
    }]
  };
});

Transport Options

Transport	Use Case
stdio	Local CLI tools
HTTP/SSE	Web services, remote servers

Security Considerations

• Validate all input parameters
• Sanitize file paths
• Rate limit API calls
• Don't expose secrets
• Log all tool invocations
• Handle timeouts gracefully

Detailed References

• MCP Patterns: See references/mcp-patterns.md
• AI/ML Integration: See references/ai-ml-integration.md