Claude with MCP

Before Claude can use a tool, you have to tell the client where the server is. This little config file is that introduction — it registers one MCP server named docs so Claude Code knows how to start it and talk to it.

1. mcpServers is a list of servers you're registering. Each key ("docs" here) is a name you choose for one server.
2. command and args together tell the client how to launch the server: run python with the argument mcp/server.py. So the client literally starts your script as a separate program.
3. The comment calls it a stdio server — it means the client and server talk by writing back and forth over the program's normal input/output pipes (standard in / standard out), the simplest way to connect a local server.
4. Once this is saved, Claude discovers the tools that server exposes and can call them during a chat — you don't wire up each tool by hand.

What the output means: Nothing prints — this is configuration, not a program. Its effect is that Claude Code now sees the docs server and its tools.

Try this: You can do the same thing without editing the file by running claude mcp add (shown in the comment). Try changing "docs" to another name and note that the name is just a label you pick.

This is a complete — if tiny — MCP server: the program on the other end that actually does the work. The surprise is how little code it takes. FastMCP handles all the protocol plumbing; you just write ordinary Python functions and mark which ones are tools.

1. mcp = FastMCP("docs") creates the server object and names it docs. This object knows how to speak the MCP protocol so you don't have to.
2. The @mcp.tool() line above the function is a decorator — it tells the server "expose this function to Claude as a callable tool." Without it, the function would just be normal Python that Claude can't see.
3. The triple-quoted line inside the function is the docstring, and it is not just a comment: MCP sends it to Claude as the tool's description. Notice it says when to use the tool ("policy/product questions") — that's how Claude decides to call it.
4. The function body is plain Python: it searches a small dictionary and returns the matching values. The -> list[str] type hint tells MCP the tool gives back a list of strings.
5. mcp.run(transport="stdio") at the bottom starts the server and makes it listen over stdio — the same channel the config file above expected.

What the output means: Run directly, it prints nothing and waits: a server sits idle until a client connects and asks it to run search_docs. Calling search_docs("refund") would return ["Refunds within 30 days."].

Try this: Add a second entry to the corpus dictionary and a matching query word. Every function you decorate with @mcp.tool() becomes a new capability Claude can call.

Claude chooses which tool to call almost entirely from the tool's description. A vague description means the tool never gets used at the right moment. This little checker scores a description the way a reviewer would, so you catch weak ones before shipping.

1. d = desc.lower() makes a lowercase copy so the checks aren't fooled by capitalization. notes = [] starts an empty list to collect problems.
2. The first if looks for trigger words like "when" or "for". If none appear, the description never says when to use the tool, so it adds a note. Saying when-to-use is the single most important thing a description does.
3. The second if flags descriptions shorter than 25 characters as too terse — too little text for Claude to reliably match to a user's request.
4. return (not notes), notes hands back a pair: True if the list of problems is empty (a good description), plus the list itself so you can read what to fix.
5. The two print calls test it: a bad description ("searches") and a good one that names when to use it.

What the output means: First line is (False, ['say WHEN to use it', 'too terse to trigger reliably']) — two problems found. Second is (True, []) — the good description passes with no notes.

Try this: Feed it your own server's docstring from server.py. If it fails, rewrite the docstring to name a concrete when — e.g. "Use for refund and support-hours questions."

An MCP server is real software that runs on your machine with your permissions — it can touch files, networks and systems. So connecting one is a trust decision, not a casual install. This function turns that judgment into a repeatable checklist you run before enabling a server.

1. risks = [] starts an empty list; each check that fails will append a reason, and an empty list at the end means the server looks safe.
2. The first check flags a server whose trusted_source is missing or false — you don't know who wrote it.
3. The second flags a server that has network_access but has not been audited — code that can reach the internet and hasn't been reviewed is a classic danger.
4. The third looks for a delete tool with no human_gate — a destructive action with no human approval step. That combination is exactly what you don't want running unattended.
5. return (not risks), risks gives back True only when zero risks were found, plus the list of any concerns.

What the output means: First line (True, []) — the trusted, audited, search-only server passes. Second (False, ['untrusted source', 'network access, unaudited', 'destructive tool, no gate']) — three red flags on the sketchy server.

Try this: Add a rule of your own — e.g. flag any server exposing a "write" tool without a gate. Treat a third-party MCP server like installing an app: vet the source, review its tools, prefer least privilege.