Claude Academy Guide

Starting path for an MCP server that wraps an external API

1. Learn the model. An MCP server exposes tools (actions Claude can call), resources (readable data) and prompts (reusable templates). For an API wrapper, you'll mostly write tools.
2. Pick an SDK. Use the official TypeScript SDK (@modelcontextprotocol/sdk) or the Python SDK (mcp, with its FastMCP helper). Python's FastMCP is the quickest to start with.
3. Build one tool first. Choose a single read-only API endpoint, such as "get weather" or "search issues". Give the tool:
   • a clear name and description, because Claude uses these to decide when to call it
   • typed input parameters
   • a short, readable result, not the raw JSON dump
4. Handle the API details. Read the API key from an environment variable and never hardcode it. Return clear error messages when a call fails, and respect the API's rate limits.
5. Use stdio transport for local development. Your server runs as a subprocess, and Claude Code talks to it over stdin/stdout. Never print() to stdout in a stdio server, because that corrupts the protocol. Log to stderr instead.
6. Register it with Claude Code.

   claude mcp add my-api -e API_KEY=xxx -- python /path/to/server.py
   

   Then run /mcp inside Claude Code to confirm it connected, and ask Claude to use your tool.
7. Debug with the MCP Inspector. Run npx @modelcontextprotocol/inspector to call your tools directly without Claude in the loop.
8. Expand. Add more endpoints, then consider remote (HTTP) transport and OAuth if you want to share the server.

A good first session is to ask Claude Code to scaffold the server for the API you have in mind. Paste in the API docs link and ask it to build one tool, then test it with the Inspector.

You might also find the Claude Code hub on Claude Academy helpful. It collects the learning material for Claude Code. The resources library is searchable if you want something specific to MCP.