MCP Servers: Extending AI Capabilities

Introduction

The Model Context Protocol (MCP) is a standardized way to connect AI models to external data sources and tools. Developed by Anthropic, MCP solves a fundamental problem: large language models are powerful but isolated—they can't access your databases, APIs, file systems, or real-time data without integration. MCP provides a universal protocol that any AI application can use to connect to any tool or data source, eliminating the need for custom integrations for each AI model and each external system.

Before MCP, every AI application had to build bespoke integrations. If you wanted your AI assistant to read your GitHub repositories, query your database, and send Slack messages, you'd write custom code for each integration. MCP standardizes this with a protocol that defines how tools are described, how resources are accessed, and how prompts are templated. This means a single MCP server can work with Claude, GPT, Gemini, or any other model that supports the protocol.

Understanding MCP Servers: Core Concepts

MCP defines three primary primitives: Tools, Resources, and Prompts. Tools are functions that the AI model can call to perform actions—like creating a database record, sending an email, or querying an API. Resources are data sources that provide context to the model—like file contents, database schemas, or API documentation. Prompts are reusable templates that guide the model's behavior for specific tasks.

The protocol uses JSON-RPC 2.0 over stdio or HTTP/SSE for communication. The MCP server runs as a separate process and communicates with the AI client through this protocol. This separation is intentional—it allows MCP servers to run in isolated environments, be developed in any language, and be shared across different AI applications.

An MCP server advertises its capabilities during the initialization handshake. The client and server negotiate which features are supported, including whether the server supports tools, resources, prompts, and sampling. This capability negotiation ensures forward compatibility and allows servers to implement only the features they need.

Tool definitions follow a JSON Schema format that describes the tool's name, description, and input parameters. The AI model uses these descriptions to decide when and how to call each tool. Well-written descriptions are critical—they directly influence the model's ability to use tools correctly.

Resources use URI-based addressing, similar to file paths or URLs. A resource URI like file:///path/to/document or postgres://database/schema uniquely identifies each data source. Resources can be static (always available) or dynamic (generated on demand based on templates).

Architecture and Design Patterns

MCP Server Architecture

An MCP server consists of several layers: the transport layer (stdio or HTTP), the protocol handler (JSON-RPC), the capability handlers (tools, resources, prompts), and the business logic that implements each capability.

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import {
    CallToolRequestSchema,
    ListToolsRequestSchema,
    ListResourcesRequestSchema,
    ReadResourceRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';
 
const server = new Server(
    { name: 'my-mcp-server', version: '1.0.0' },
    { capabilities: { tools: {}, resources: {} } }
);
 
// List available tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
        {
            name: 'query_database',
            description: 'Execute a read-only SQL query against the database',
            inputSchema: {
                type: 'object',
                properties: {
                    query: {
                        type: 'string',
                        description: 'SQL query to execute (SELECT only)',
                    },
                    database: {
                        type: 'string',
                        description: 'Database name',
                        default: 'main',
                    },
                },
                required: ['query'],
            },
        },
    ],
}));
 
// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
 
    switch (name) {
        case 'query_database':
            return await handleDatabaseQuery(args);
        default:
            throw new Error(`Unknown tool: ${name}`);
    }
});

Tool Design Patterns

Well-designed tools follow specific patterns that maximize the AI model's effectiveness:

Single Responsibility: Each tool should do one thing well. Instead of a generic manage_database tool, create separate query_database, insert_record, and update_record tools. This makes tool descriptions clearer and helps the model choose the right tool.

Descriptive Names and Descriptions: Tool names should be verb-noun combinations that clearly describe the action. Descriptions should explain what the tool does, when to use it, and any limitations.

Input Validation: Validate all inputs at the tool boundary using JSON Schema. Return clear error messages that help the model understand what went wrong and how to fix it.

// Good tool definition
{
    name: 'search_documents',
    description: 'Search through the knowledge base for documents matching a query. Returns the top 5 most relevant results with relevance scores. Use this when the user asks about specific topics or needs to find information in the document collection.',
    inputSchema: {
        type: 'object',
        properties: {
            query: {
                type: 'string',
                description: 'Natural language search query',
            },
            category: {
                type: 'string',
                enum: ['technical', 'business', 'legal'],
                description: 'Optional category filter',
            },
            maxResults: {
                type: 'number',
                minimum: 1,
                maximum: 20,
                default: 5,
                description: 'Maximum number of results to return',
            },
        },
        required: ['query'],
    },
}

Resource Patterns

Resources provide context that the model can reference during conversations:

// List available resources
server.setRequestHandler(ListResourcesRequestSchema, async () => ({
    resources: [
        {
            uri: 'schema://database/main',
            name: 'Database Schema',
            description: 'Complete schema of the main database including tables, columns, and relationships',
            mimeType: 'application/json',
        },
        {
            uri: 'docs://api/v2',
            name: 'API Documentation',
            description: 'REST API v2 documentation including endpoints, parameters, and examples',
            mimeType: 'text/markdown',
        },
    ],
}));
 
// Read resource content
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
    const { uri } = request.params;
 
    switch (uri) {
        case 'schema://database/main':
            return {
                contents: [{
                    uri,
                    mimeType: 'application/json',
                    text: JSON.stringify(await getDatabaseSchema(), null, 2),
                }],
            };
        case 'docs://api/v2':
            return {
                contents: [{
                    uri,
                    mimeType: 'text/markdown',
                    text: await readApiDocs(),
                }],
            };
        default:
            throw new Error(`Unknown resource: ${uri}`);
    }
});

Step-by-Step Implementation

Setting Up an MCP Server Project

# Create project directory
mkdir my-mcp-server && cd my-mcp-server
npm init -y
 
# Install MCP SDK
npm install @modelcontextprotocol/sdk zod
 
# Create TypeScript config
cat > tsconfig.json << 'EOF'
{
    "compilerOptions": {
        "target": "ES2022",
        "module": "Node16",
        "moduleResolution": "Node16",
        "outDir": "./dist",
        "rootDir": "./src",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "declaration": true
    },
    "include": ["src/**/*"]
}
EOF

Implementing a Complete MCP Server

Here's a full MCP server that provides file system access and code analysis:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
import * as fs from 'fs/promises';
import * as path from 'path';
 
const server = new Server(
    { name: 'filesystem-server', version: '1.0.0' },
    { capabilities: { tools: {}, resources: {} } }
);
 
// Tool schemas
const ReadFileSchema = z.object({
    path: z.string().describe('Absolute path to the file'),
    encoding: z.enum(['utf-8', 'base64']).default('utf-8'),
});
 
const WriteFileSchema = z.object({
    path: z.string().describe('Absolute path to the file'),
    content: z.string().describe('Content to write'),
    createDirs: z.boolean().default(false).describe('Create parent directories if they don\'t exist'),
});
 
const ListDirectorySchema = z.object({
    path: z.string().describe('Directory path to list'),
    recursive: z.boolean().default(false),
    pattern: z.string().optional().describe('Glob pattern to filter files'),
});
 
// Register tools
server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
        {
            name: 'read_file',
            description: 'Read the contents of a file. Supports text and binary (base64) encoding.',
            inputSchema: ReadFileSchema,
        },
        {
            name: 'write_file',
            description: 'Write content to a file. Creates the file if it doesn\'t exist.',
            inputSchema: WriteFileSchema,
        },
        {
            name: 'list_directory',
            description: 'List files and directories at the specified path.',
            inputSchema: ListDirectorySchema,
        },
        {
            name: 'search_files',
            description: 'Search for text patterns across files in a directory.',
            inputSchema: z.object({
                path: z.string(),
                pattern: z.string().describe('Text or regex pattern to search for'),
                filePattern: z.string().optional().describe('File glob pattern (e.g., "*.ts")'),
            }),
        },
    ],
}));
 
// Handle tool calls
server.setRequestHandler(CallToolRequestSchema, async (request) => {
    const { name, arguments: args } = request.params;
 
    try {
        switch (name) {
            case 'read_file': {
                const { path: filePath, encoding } = ReadFileSchema.parse(args);
                const content = await fs.readFile(filePath, encoding);
                return {
                    content: [{
                        type: 'text',
                        text: encoding === 'base64'
                            ? content.toString('base64')
                            : content,
                    }],
                };
            }
 
            case 'write_file': {
                const { path: filePath, content, createDirs } = WriteFileSchema.parse(args);
                if (createDirs) {
                    await fs.mkdir(path.dirname(filePath), { recursive: true });
                }
                await fs.writeFile(filePath, content, 'utf-8');
                return {
                    content: [{
                        type: 'text',
                        text: `Successfully wrote ${content.length} bytes to ${filePath}`,
                    }],
                };
            }
 
            case 'list_directory': {
                const { path: dirPath, recursive, pattern } = ListDirectorySchema.parse(args);
                const entries = await listDirectory(dirPath, recursive, pattern);
                return {
                    content: [{
                        type: 'text',
                        text: JSON.stringify(entries, null, 2),
                    }],
                };
            }
 
            case 'search_files': {
                const { path: searchPath, pattern, filePattern } = args as any;
                const results = await searchFiles(searchPath, pattern, filePattern);
                return {
                    content: [{
                        type: 'text',
                        text: JSON.stringify(results, null, 2),
                    }],
                };
            }
 
            default:
                throw new Error(`Unknown tool: ${name}`);
        }
    } catch (error) {
        return {
            content: [{
                type: 'text',
                text: `Error: ${error instanceof Error ? error.message : String(error)}`,
            }],
            isError: true,
        };
    }
});
 
// Helper functions
async function listDirectory(dirPath: string, recursive: boolean, pattern?: string) {
    const entries = await fs.readdir(dirPath, { withFileTypes: true });
    const results = [];
 
    for (const entry of entries) {
        const fullPath = path.join(dirPath, entry.name);
        if (entry.isDirectory()) {
            results.push({ type: 'directory', name: entry.name, path: fullPath });
            if (recursive) {
                const subEntries = await listDirectory(fullPath, true, pattern);
                results.push(...subEntries);
            }
        } else {
            if (!pattern || entry.name.match(new RegExp(pattern))) {
                const stat = await fs.stat(fullPath);
                results.push({
                    type: 'file',
                    name: entry.name,
                    path: fullPath,
                    size: stat.size,
                    modified: stat.mtime,
                });
            }
        }
    }
    return results;
}
 
async function searchFiles(searchPath: string, pattern: string, filePattern?: string) {
    const regex = new RegExp(pattern, 'gi');
    const results: Array<{ file: string; line: number; match: string }> = [];
 
    async function searchDir(dirPath: string) {
        const entries = await fs.readdir(dirPath, { withFileTypes: true });
        for (const entry of entries) {
            const fullPath = path.join(dirPath, entry.name);
            if (entry.name === 'node_modules' || entry.name === '.git') continue;
 
            if (entry.isDirectory()) {
                await searchDir(fullPath);
            } else if (!filePattern || entry.name.match(new RegExp(filePattern))) {
                const content = await fs.readFile(fullPath, 'utf-8');
                const lines = content.split('\n');
                lines.forEach((line, i) => {
                    if (regex.test(line)) {
                        results.push({ file: fullPath, line: i + 1, match: line.trim() });
                    }
                    regex.lastIndex = 0;
                });
            }
        }
    }
 
    await searchDir(searchPath);
    return results;
}
 
// Start the server
async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
    console.error('MCP server running on stdio');
}
 
main().catch(console.error);

Configuring the MCP Server

Create a configuration file for Claude Desktop or other MCP clients:

{
    "mcpServers": {
        "filesystem": {
            "command": "node",
            "args": ["./dist/index.js"],
            "env": {
                "ALLOWED_PATHS": "/home/user/projects,/home/user/documents"
            }
        }
    }
}

Real-World Use Cases and Case Studies

Use Case 1: Database Query Assistant

An MCP server that provides database access enables natural language database queries. The AI model generates SQL based on user questions, the MCP server executes them safely (with read-only access and query validation), and returns formatted results. This pattern is powerful for business intelligence, allowing non-technical users to query databases conversationally.

Use Case 2: Development Environment Integration

An MCP server that integrates with Git, CI/CD pipelines, and issue trackers gives AI assistants deep development context. The model can read code, check commit history, create pull requests, update Jira tickets, and trigger deployments—all through standardized MCP tools. This eliminates context switching and enables the AI to perform complete development workflows.

Use Case 3: Knowledge Base Access

Organizations with large internal documentation benefit from MCP servers that index and search knowledge bases. The AI model can answer questions by searching across Confluence, Notion, Google Docs, and internal wikis. The MCP server handles authentication, search ranking, and content retrieval, while the model focuses on synthesizing answers from retrieved documents.

Best Practices for Production

Validate all inputs strictly: Use JSON Schema or Zod to validate every tool input. Reject invalid inputs with clear error messages that help the model correct its request.
Implement rate limiting: AI models can call tools rapidly. Implement rate limiting to prevent overwhelming downstream services. Return clear rate limit messages so the model can adjust its behavior.
Use read-only defaults: When tools can modify data, default to read-only mode. Require explicit confirmation for destructive operations. Implement dry-run modes for testing.
Provide rich error messages: Error messages should explain what went wrong, why, and how to fix it. "Query failed" is useless; "Query failed: table 'users' doesn't exist. Available tables: customers, accounts" is actionable.
Implement authentication and authorization: MCP servers that access external services need proper auth. Use environment variables for secrets, implement token refresh, and enforce least-privilege access.
Log all tool calls: Log every tool invocation with parameters, results, and timing. This audit trail is essential for debugging, security monitoring, and understanding how the AI uses your tools.
Version your MCP server: Include version numbers in the server configuration and advertise capabilities based on version. This enables backward compatibility when adding new tools or changing schemas.
Handle timeouts gracefully: Set reasonable timeouts for external service calls. Return partial results when possible instead of failing entirely. The model can work with partial information better than no information.

Common Pitfalls and Solutions

Pitfall	Impact	Solution
Vague tool descriptions	Model misuses tools or avoids them	Write specific descriptions with examples of when to use each tool
No input validation	Security vulnerabilities and errors	Validate all inputs with JSON Schema before processing
Exposing sensitive data in responses	Security breaches	Filter sensitive fields from tool responses; implement data masking
No error handling	Server crashes on unexpected inputs	Wrap all handlers in try/catch with descriptive error messages
Tool proliferation	Model confusion with too many choices	Group related tools; provide 5-15 well-designed tools max
Synchronous blocking	Server becomes unresponsive	Use async/await for all I/O operations; implement timeouts

Performance Optimization

MCP server performance directly impacts AI application responsiveness. Cache frequently accessed resources to avoid repeated database queries or API calls:

class ResourceCache {
    private cache = new Map<string, { data: any; expiry: number }>();
 
    async get(key: string, fetcher: () => Promise<any>, ttlMs: number = 60000) {
        const cached = this.cache.get(key);
        if (cached && cached.expiry > Date.now()) {
            return cached.data;
        }
 
        const data = await fetcher();
        this.cache.set(key, { data, expiry: Date.now() + ttlMs });
        return data;
    }
 
    invalidate(pattern: string) {
        for (const key of this.cache.keys()) {
            if (key.match(pattern)) {
                this.cache.delete(key);
            }
        }
    }
}

Use connection pooling for database connections and HTTP keep-alive for API clients. Implement streaming responses for large datasets—return results incrementally instead of loading everything into memory.

// Streaming tool response for large datasets
async function* streamQueryResults(query: string) {
    const cursor = db.cursor(query);
    for await (const row of cursor) {
        yield { type: 'text', text: JSON.stringify(row) };
    }
}

Comparison with Alternatives

Feature	MCP	Function Calling	Plugins	Custom APIs
Standardization	Open protocol	Per-provider	Per-platform	None
Model Agnostic	Yes	No	No	Yes
Discovery	Built-in	Manual	Manual	Manual
Resource Access	Native	Via tools	Native	Custom
Prompt Templates	Native	No	Custom	No
Ecosystem	Growing	Per-provider	Platform-specific	N/A

MCP provides the most standardized approach for connecting AI to external systems. Function calling is simpler but vendor-locked. Plugins are platform-specific (ChatGPT, etc.). Custom APIs give maximum control but require integration work for each model.

Advanced Patterns and Techniques

Multi-Transport MCP Servers

Support both stdio and HTTP transports for flexibility:

import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
import express from 'express';
 
async function startServer(mode: string) {
    const server = createServer();
 
    if (mode === 'stdio') {
        const transport = new StdioServerTransport();
        await server.connect(transport);
    } else if (mode === 'http') {
        const app = express();
        let transport: SSEServerTransport;
 
        app.get('/sse', (req, res) => {
            transport = new SSEServerTransport('/messages', res);
            server.connect(transport);
        });
 
        app.post('/messages', (req, res) => {
            transport.handlePostMessage(req, res);
        });
 
        app.listen(3000);
    }
}

Dynamic Tool Registration

class DynamicMCPServer {
    private tools = new Map<string, ToolDefinition>();
 
    registerTool(definition: ToolDefinition, handler: ToolHandler) {
        this.tools.set(definition.name, { definition, handler });
    }
 
    unregisterTool(name: string) {
        this.tools.delete(name);
    }
 
    // Handler returns current tool list
    listTools() {
        return Array.from(this.tools.values()).map(t => t.definition);
    }
}

Testing Strategies

Test MCP servers with the MCP Inspector tool and unit tests:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 
describe('MCP Server', () => {
    let client: Client;
    let server: Server;
 
    beforeEach(async () => {
        server = createServer();
        const [clientTransport, serverTransport] = InMemoryTransport.createPair();
        await server.connect(serverTransport);
        client = new Client({ name: 'test', version: '1.0.0' });
        await client.connect(clientTransport);
    });
 
    it('should list available tools', async () => {
        const { tools } = await client.listTools();
        expect(tools.length).toBeGreaterThan(0);
        expect(tools[0].name).toBe('read_file');
    });
 
    it('should execute read_file tool', async () => {
        const result = await client.callTool({
            name: 'read_file',
            arguments: { path: '/tmp/test.txt' },
        });
        expect(result.content[0].type).toBe('text');
    });
 
    it('should handle invalid tool calls', async () => {
        const result = await client.callTool({
            name: 'nonexistent_tool',
            arguments: {},
        });
        expect(result.isError).toBe(true);
    });
});

Future Outlook

MCP is rapidly evolving with new features like streaming tool responses, bidirectional communication, and resource subscriptions. The protocol is being adopted beyond Anthropic—OpenAI, Google, and open-source projects are implementing MCP support. The MCP server ecosystem is growing with pre-built servers for GitHub, Slack, PostgreSQL, and hundreds of other services. Standardization through the MCP specification ensures long-term compatibility across AI platforms.

Conclusion

MCP servers bridge the gap between AI models and external systems through a standardized protocol. By implementing tools, resources, and prompts, you give AI assistants the ability to interact with your specific infrastructure and data. The protocol's model-agnostic design ensures your integrations work across AI platforms.

Key takeaways: design tools with clear descriptions and strict validation, implement proper authentication and rate limiting, and cache frequently accessed resources. Start with the MCP SDK, test with MCP Inspector, and share your servers with the community. The investment in MCP infrastructure pays off through reusable, model-independent AI integrations.

For further reading, consult the MCP specification, the Anthropic MCP documentation, and the growing collection of community MCP servers on GitHub.

Minh Vo

Slaying code & making it lit fr fr 🔥 tagline