Custom MCP Server with Claude

Before the full build, this short sketch shows the shape of an MCP server using the real Python SDK. Three little functions, each marked with a decorator (the @mcp.... line above it) that tells the server "publish this as a tool / a resource / a prompt". That's the entire pattern.

1. mcp = FastMCP("my-company-tools") creates the server and gives it a name. Everything you publish attaches to this mcp object.
2. @mcp.tool() above create_ticket publishes an action — something the model can do. It takes inputs (title, priority) and returns a result.
3. @mcp.resource("docs://{doc_id}") publishes readable data. The {doc_id} in the address is a slot the client fills in to say which document it wants — read-only, no side effects.
4. @mcp.prompt() publishes a reusable template: a function that builds a prompt string every connected client can share, instead of each one re-writing it.

What the output means: Nothing runs yet — this is just the shape. Notice the three decorators map one-to-one onto the three boxes on the right of the architecture diagram: tool, resource, prompt.

Try this: Read just the three @mcp.... lines top to bottom and say out loud "action, data, template". The real server you build next is this exact skeleton filled in.

This sets up an isolated workspace so the project's packages don't collide with anything else on your computer. You run these lines once, in a terminal, before writing any code.

1. mkdir -p mcp-server/tests makes the project folder (and a tests sub-folder in one go); cd mcp-server moves you into it so the later steps land in the right place.
2. python3 -m venv .venv creates a virtual environment — a private copy of Python for this project. source .venv/bin/activate switches it on (the comment shows the different Windows command).
3. pip install "mcp[cli]" pytest downloads the MCP SDK (the real library this server is built on) and pytest (the test runner used in Step 4).
4. pip freeze > requirements.txt writes the exact installed versions to a file, so anyone else can recreate the same environment later.

What the output means: The last line, Successfully installed mcp-1.2.0 pytest-8.3.4 ..., confirms the two libraries downloaded. The (.venv) at the front of your prompt means the virtual environment is active.

Try this: If mcp[cli] refuses to install, run python3 --version — the SDK needs Python 3.10 or newer. That is the single most common snag here.

Real MCP servers sit in front of a real system — a ticketing API, a database. So we don't need one to learn, this file is a fake stand-in: a tiny ticket store that lives only in memory. It lets the whole project run offline, with no key and no external service.

1. class Store bundles the data and the operations on it together. __init__ runs once when the store is created: self._tickets = {} is an empty dictionary that will hold tickets by id, and self._next = 1 is the counter for the next id.
2. create(...) makes a new ticket: it turns the counter into a string id, bumps the counter, builds a dictionary with the ticket's fields (defaulting status to "open"), stores it, and returns it.
3. get(tid) looks a ticket up by id. If the id isn't there it raises a KeyError — failing loudly on missing data rather than returning something wrong.
4. store = Store() at the bottom creates one shared instance. The server and the tests both import this same store, so they all see the same tickets.

What the output means: This file prints nothing on its own — it just defines the store. Its job is to give server.py something real-looking to call.

Try this: Notice there's no database and no network here — just a dictionary. Swapping this fake for a real ticketing API later would mean changing only this file; the server on top of it stays the same.

This is the heart of the project: a real MCP server built with the SDK. It publishes exactly one of each primitive — a tool, a resource, and a prompt — and carefully validates the one that writes data. Compare it to the shape sketch from Section 4; this is that skeleton filled in for real.

1. from backend import store pulls in the shared fake store from Step 2, and mcp = FastMCP("ticketing") creates the named server.
2. @mcp.tool() publishes create_ticket — the write action. Because writes are risky, it checks its inputs first: the priority must be one of VALID_PRIORITIES (low/med/high) and the title must not be blank — otherwise it raises a ValueError. Only then does it call store.create(...).
3. @mcp.resource("ticket://{ticket_id}") publishes get_ticket — read-only. A client asks for ticket://5 and gets back a formatted one-line summary; it can't change anything.
4. @mcp.prompt() publishes triage, a shared template that wraps a ticket in a standard instruction any client can reuse.
5. if __name__ == "__main__": mcp.run() starts the server when you run the file directly. The comment notes it uses stdio transport by default — it talks over the terminal's input/output, with no network exposure.

What the output means: Running this file starts a live MCP server that waits for a client to connect. On its own it prints nothing and just listens.

Try this: Look at what create_ticket refuses: a bad priority and an empty title. That is least-privilege design — a narrow, validated action instead of a dangerous "do anything" tool.

These tests prove the server works without connecting a model or a client — they just import the functions and call them like normal Python. That's the payoff of the fake backend: you can test an MCP server exactly like any other API.

1. The SDK decorators wrap your functions, so server.create_ticket is no longer the plain function. The _create, _get and _triage helpers use getattr(..., "fn", ...) to reach the original function underneath (the comment gives the fallback for other SDK versions).
2. test_create_ticket_returns_id makes a ticket and asserts it has an id and the right priority — the happy path works.
3. test_invalid_priority_rejected and test_empty_title_rejected use with pytest.raises(ValueError): to assert the tool refuses bad input. Here a passing test means the code correctly threw an error.
4. test_get_ticket_reads_back creates then reads a ticket to prove the resource returns it; test_get_unknown_ticket_errors checks a missing id raises KeyError; test_triage_prompt_includes_ticket checks the prompt template actually contains the ticket text.

What the output means: Six functions whose names start with test_ — pytest finds and runs each one automatically. Together they cover the tool, the resource, and the prompt.

Try this: A test that expects an error (pytest.raises) passes only when the error does happen. It's checking that your validation guards actually fire.

This one command runs the whole test file and reports the result. It's how you confirm the server behaves correctly before wiring it to anything.

1. python -m pytest tests/ -v tells pytest to look in the tests/ folder. The -v (verbose) flag makes it list every test by name instead of just printing dots.
2. Each line ends in PASSED — pytest ran that test function and its assertions all held.
3. The final line, 6 passed in 0.10s, is the summary: all six tests passed, and it took a fraction of a second because there's no network or model involved.

What the output means: 6 passed is the green light: your tool validates input, your resource reads back data, and your prompt renders — all offline.

Try this: Break one test on purpose — change "high" to "huge" in the first test — re-run, and read the FAILED output. Learning to read a failure is as useful as seeing them pass.

This small JSON file is how you register your server with Claude Code. It doesn't run any Python itself — it just tells the client how to start your server so Claude can use its tools.

1. "mcpServers" is the section Claude Code reads to find MCP servers. Inside it, "ticketing" is the name you're giving this one.
2. "command": "python" plus "args": ["server.py"] is literally the instruction "to start this server, run python server.py" — exactly the file you wrote in Step 3.
3. Because server.py uses stdio by default, Claude Code launches it and talks to it over that process's input/output — no ports, no network.

What the output means: The console block below shows the result: you ask Claude in plain English to open a ticket, and it calls your create_ticket tool with the right arguments and reports back Created ticket #1.

Try this: This is the whole point paying off: you wrote one small server, and now a real client can drive your tool from natural language. Add a second server under mcpServers the same way and Claude sees both.