Building Your First MCP Server: A Step-by-Step Tutorial

MCP servers let you give AI agents access to your custom tools, APIs, and data sources through a standardized protocol. Instead of building a one-off integration for each AI client, you build one MCP server that works with Claude Code, Cursor, Windsurf, and any other MCP-compatible client. Common use cases: connecting agents to internal APIs, wrapping databases for AI access, exposing domain-specific tools (Jira, Confluence, Slack), or creating specialized development tools.

MCP provides official SDKs for two languages: TypeScript SDK (@modelcontextprotocol/sdk) • Best for: Node.js developers, web-focused tools • Install: npm install @modelcontextprotocol/sdk • Runs as a Node.js process Python SDK (mcp) • Best for: Python developers, data/ML tools • Install: pip install mcp • Uses asyncio for concurrent operations Both SDKs provide the same capabilities. Choose based on your language preference and existing tooling.

Tools are the primary capability of most MCP servers. Each tool needs three things: 1. Name — A clear, action-oriented name like 'search_issues' or 'create_branch'. 2. Description — A detailed description that helps the LLM understand when and how to use the tool. This is critical — the AI reads this to decide whether to call your tool. 3. Input Schema — A JSON Schema defining the parameters. Use clear parameter names and descriptions. The quality of your tool descriptions directly impacts how well agents use them. Be specific: instead of 'query' → 'SQL query to execute against the production database. Must be a SELECT statement.' The more context you give the LLM, the better it will use your tools.

Each tool needs a handler function that receives the validated input parameters and returns a result. Handlers should: • Validate inputs — Even though the schema provides basic validation, add business logic checks. • Handle errors gracefully — Return informative error messages that help the agent recover. • Be idempotent when possible — Agents may retry failed tool calls. • Return structured data — JSON objects are easier for agents to parse than free-form text. • Include context — Return not just the result, but enough context for the agent to understand what happened.

MCP supports two transport mechanisms: stdio (Standard Input/Output) • The MCP client spawns your server as a child process • Communication happens over stdin/stdout • Best for: local development tools, CLI integrations • How to configure: In claude_desktop_config.json or .claude/settings.json, specify the command to run your server HTTP + Server-Sent Events (SSE) • Your server runs as an HTTP service • Client connects via HTTP POST (requests) and SSE (streaming responses) • Best for: remote/shared servers, cloud-hosted tools • More complex to set up but enables centralized deployment Start with stdio for development and testing. Move to HTTP+SSE when you need to share the server across teams or deploy it remotely.

The fastest way to test your MCP server is with Claude Code: 1. Add your server to the MCP configuration (project or global settings) 2. Start Claude Code — it will connect to your server and discover tools 3. Ask Claude to use your tools naturally: 'Search for open issues about authentication' 4. Watch the tool calls in the terminal output Common debugging tips: • Check stderr output from your server for error messages • Use the MCP Inspector tool for protocol-level debugging • Start with simple tools and add complexity incrementally • Test edge cases: what happens when the tool returns an error? Empty results? Very large results?

When moving your MCP server to production: • Authentication — Add API key or OAuth authentication for sensitive tools. • Rate limiting — Prevent agents from overwhelming your APIs. • Logging — Log all tool invocations for debugging and audit trails. • Timeouts — Set reasonable timeouts to prevent hanging tool calls. • Versioning — Use semantic versioning for your tool schemas. • Documentation — Publish a README with tool descriptions, examples, and configuration instructions. The MCP ecosystem is growing rapidly — publishing your server on npm or PyPI makes it discoverable and usable by the entire community.