A custom Model Context Protocol (MCP) server provides AI agents with standardized access to external APIs, databases, and local tools using JSON-RPC 2.0. By decoupling tool definitions from proprietary agent frameworks, MCP allows seamless interoperability across Claude Desktop, OpenAI ChatGPT, and local coding assistants with latency under 120 ms.
Related to multiple guides. For full context, see our ChatGPT Guide & AI Agents Guide.
The Model Context Protocol (MCP) has established itself as the open industry standard for connecting LLM clients (Anthropic Claude Desktop, Claude Code, ChatGPT, Cursor) to external tools, databases, and APIs. Building a high-performance custom MCP server requires mastering JSON-RPC 2.0 transport mechanisms (stdio vs. SSE/HTTP) and designing token-efficient tool schemas. Keeping tool parameter definitions concise and structured saves up to 40 % of system prompt token overhead, preventing context saturation and model confusion.
MCP Protocol Architecture Core Rules
- Transport Layer: Local tools use
stdio(standard input/output process pipes). Remote and cloud servers useSSE(Server-Sent Events) or HTTP streaming. - Tool Schema Budget: All tool definitions are injected into the client LLM’s system prompt. Keep total MCP tool definitions under 2,500 tokens.
- Stateless Tool Design: Tools should execute atomically and return structured JSON responses with explicit error statuses.
1. Transport Mechanisms: stdio vs. Server-Sent Events (SSE)
| Feature | stdio Transport | SSE / HTTP Transport |
|---|---|---|
| Execution Context | Local child process spawned by host | Remote server / cloud microservice |
| Communication | Standard input / output pipes (stdin/stdout) | HTTP POST + Server-Sent Events stream |
| Security / Auth | Local OS user permissions & sandbox | Bearer Tokens, OAuth 2.0, mTLS |
| Typical Use Cases | Local filesystem, Git, SQLite, Shell CLI | PostgreSQL, CRM APIs, Stripe, Multi-tenant SaaS |
2. Designing Token-Efficient Tool Schemas
One of the most common pitfalls when developing MCP servers is bloating the tool description with verbose paragraphs. Remember: every single MCP tool definition consumes context window space on every user prompt.
Best Practices for Tool Definitions:
- Concise Functional Descriptions: 1–2 sentences explaining exactly when and why to call the tool.
- Strong Typing via JSON Schema: Use enums, strict types, and required property arrays to guide model output without ambiguity.
- Granular Tool Grouping: Group related actions (e.g.,
manage_databasewith anaction: "read" | "write" | "migrate"parameter) rather than creating 15 separate tool definitions.
3. Python FastMCP Implementation Example
from mcp.server.fastmcp import FastMCP
# Initialize FastMCP Server
mcp = FastMCP("DataService")
@mcp.tool()
def query_metrics(metric_name: str, days: int = 7) -> str:
# Retrieve aggregated performance metrics for a specified system metric over N days
return '{"metric": "' + metric_name + '", "value": 99.4, "status": "nominal"}'
if __name__ == "__main__":
mcp.run(transport="stdio")
4. Production Security & Error Handling
- Never leak stack traces directly to the model: Catch unhandled exceptions and return structured JSON error payloads (e.g.,
{"status": "error", "code": "RESOURCE_NOT_FOUND", "message": "..."}). - Input Sanitization: Always validate file paths against directory traversal attacks (
../) and sanitize SQL parameters to prevent injection. - Execution Timeouts: Implement strict timeouts (e.g., 30s) on synchronous tool executions to prevent hanging LLM client conversations.
Frequently Asked Questions (FAQ)
Can an MCP server be used across different AI tools simultaneously?
Yes. Because MCP is an open specification, the exact same MCP server can be configured in Claude Desktop, Claude Code, Cursor, Zed, and custom enterprise agent frameworks without modifying a single line of server code.
How does authentication work for remote SSE servers?
Remote MCP servers authenticate requests using standard HTTP headers (e.g., Authorization: Bearer <token>) or API keys configured in the client’s MCP configuration JSON file.
