MCP Server Best Practices

The Kitebase server from article 03: Setting Up Your First MCP Server passed its tests, so you point a version of it at Kitebase’s real API and hand it to the support team. The support lead types: “Give KITE-144 to Priya and tell the customer we’re on it.”

Every tool call succeeds. And yet: the ticket is now assigned to "Priya", a user who doesn’t exist, so nobody gets notified. Each result was 2,244 tokens of raw JSON. Kitebase was slow that afternoon, the host gave up waiting, the model tried again, and Harbor Pine got the same email twice. Nothing crashed. The server just wasn’t built for a model to use.

This article fixes that server one habit at a time. It assumes article 03: @mcp.tool(), schemas from type hints, and ToolError.

What you’ll build: a bad before.py and a good server.py for Kitebase, plus a script that runs the same support requests against both and prints what the model gets back: tools, token counts, errors, and how many emails a retry sends. It runs offline against a fake Kitebase API.

Before and after

Here are before.py’s tools, the kind you write in an afternoon by wrapping the API you have:

@mcp.tool()
async def search(query: str) -> list[dict]:
    """Search Kitebase."""
    tickets = await api.list_tickets()  # no timeout
    return [t for t in tickets if query.lower() in str(t).lower()]  # whole raw records

@mcp.tool()
async def update_ticket(id: str, data: dict) -> dict:
    """Update a ticket."""
    return await api.update_ticket(id, data)  # stores any field; crashes on a bad id

@mcp.tool()
async def send_email(to: str, subject: str, body: str) -> dict:
    """Send an email."""
    return await api.send_email(to, subject, body)  # any address, no dedupe on retry

And here’s what each version does with the support lead’s request, from the companion code’s output:

before.py isn’t broken. That’s the trap: it passes a quick test in the Inspector and fails slowly in real use. Each section below is one fix.

Names and descriptions decide which tool gets called

The model never sees your code. It picks a tool from each one’s name, description and input schema. A host connected to Kitebase and GitHub might show it two tools called search, one described as “Search Kitebase.” It will guess.

Name tools verb_noun, specific enough to make sense next to other servers’ tools. search_tickets, not search. assign_ticket, not update. The spec says names should be 1 to 128 characters of letters, digits, _, - and ., and hosts often prefix them with the server name: Claude Code shows mcp__kitebase__search_tickets.

The description (your docstring) is where the model learns when to call the tool. Four things belong in it:

• What it does, in the user’s words.
• When to use a neighbor instead. The line people skip, and the one that stops mix-ups.
• What comes back, and the limits. “Up to 10”, “the 3 most recent”.
• Anything risky. “Sends a real email.”

search_tickets in server.py:

@mcp.tool(annotations=ToolAnnotations(read_only_hint=True))
async def search_tickets(
    query: Annotated[str, Field(min_length=2, max_length=100,
                                description="Words from the title or customer name, e.g. 'sso'")],
    status: Literal["open", "in_progress", "closed", "any"] = "any",
) -> list[TicketSummary]:
    """Find Kitebase support tickets by words in their title or customer name.

    Returns up to 10 short summaries. Use get_ticket for a ticket's comments.
    For how-to guides, use search_help instead.
    """

The last two sentences point to the neighbors. Without them, “find me an article about SSO” could land on either search tool.

The gotcha: descriptions cost tokens on every request, called or not. server.py’s tool list is about 1,340 tokens against before.py’s 255. A good trade for five tools, and the reason 40 tools is a bad idea.

Small, focused tools

update_ticket(id, data: dict) looks flexible. To the model it’s a blank form: the schema for data is {"type": "object", "additionalProperties": true}, with no field names or allowed values. So it guesses {"assignee": "Priya"}, the API stores it as sent, and nobody is notified, because the username is priya.

Give each task a user actually asks for its own tool, with typed arguments:

@mcp.tool(annotations=ToolAnnotations(destructive_hint=False, idempotent_hint=True))
async def assign_ticket(
    ticket_id: TicketId,
    assignee: Annotated[str, Field(description="A teammate's username, e.g. priya")],
) -> TicketSummary:
    """Assign a Kitebase ticket to one teammate. Replaces any current assignee."""

Now the schema says exactly what’s needed, and your code knows exactly which field changes. reply_to_customer(ticket_id, message) replaces send_email the same way.

Small doesn’t mean one tool per API endpoint; article 05: Wrapping an API as an MCP Server covers why. Default to a handful of tools named after what users ask for. Split a tool when its description needs an “or” (“updates the status or the assignee or posts a reply”). Merge two when the model keeps picking the wrong one.

Validate every argument

Tool arguments are written by a model reading a human’s request. Treat them like a public HTTP request body: probably fine, never trusted. The spec says servers must validate all tool inputs.

Check in two layers. The first is the schema, which the SDK enforces before your function runs. server.py defines the ticket id once:

TicketId = Annotated[str, Field(pattern=r"^KITE-[0-9]{1,6}$", description="A ticket id such as KITE-142")]

Call assign_ticket with "ticket_id": "144" and your code never sees it:

is_error=true
Error executing tool assign_ticket: 1 validation error for assign_ticketArguments
ticket_id
  String should match pattern '^KITE-[0-9]{1,6}$' [type=string_pattern_mismatch, input_value='144', ...]

The pattern is in the schema the model reads, so it usually gets the format right first time. Use pattern, Literal and length limits wherever a schema can express the rule.

The second layer is your code, for rules that depend on live data, like which teammates exist:

    team = await call_kitebase("list_team", api.list_team())
    username = assignee.strip().lower()
    if username not in team:
        raise ToolError(f"No teammate {assignee!r}. Assignable usernames: {', '.join(team)}.")

Be forgiving where it’s harmless: "Priya" becomes priya. Be strict where a wrong guess does damage: "priyanka" is refused, not fuzzy-matched to someone.

The gotcha is arguments that end up inside something else. A model-written string pasted into SQL, a shell command or a file path is an injection bug, just as from a web form. Use parameterized queries, pass subprocess.run a list, and check paths against an allowlist.

Errors the model can act on

When a tool fails, the error message is all the model has to decide what to do next. Article 03 showed the mechanics: raise ToolError and the model reads your message; any other exception gives it a bare “Error executing tool”. Both servers, given a missing ticket and a missing teammate:

update_ticket {"id": "KITE-999", "data": {"assignee": "priya"}}          (before.py)
  Error executing tool update_ticket

assign_ticket {"ticket_id": "KITE-999", "assignee": "priya"}             (server.py)
  Error executing tool assign_ticket: No ticket KITE-999. Use search_tickets to find the id.

assign_ticket {"ticket_id": "KITE-144", "assignee": "priyanka"}          (server.py)
  Error executing tool assign_ticket: No teammate 'priyanka'. Assignable usernames: lena, priya, sam.

From the first, the model can only give up or retry blindly. From the others, it can fix the call. A good tool error says what was wrong, the valid values, and what to try next. The spec calls these tool execution errors and asks hosts to pass them to the model.

Keep secrets out of the message: it goes into the model’s context and can end up in an answer. “Kitebase returned 401: token sk_live_…” is a leak. “Kitebase rejected the server’s credentials; tell the user to check its configuration” is an instruction.

Logs go to stderr

On stdio, stdout is the wire between host and server: every line on it must be a JSON-RPC message. before.py breaks that rule with one line before mcp.run():

if __name__ == "__main__":
    print("Kitebase server starting")  # lands on stdout, where the host expects JSON-RPC
    mcp.run()

The Python SDK’s client logs this and carries on; other hosts may drop the connection:

Failed to parse JSONRPC message from server
  Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value='Kitebase server starting', ...]

server.py uses Python’s logging module, pointed at stderr:

logging.basicConfig(level=logging.INFO, stream=sys.stderr,
                    format="%(asctime)s %(levelname)s %(name)s: %(message)s")
log = logging.getLogger("kitebase")

Configure it before creating MCPServer and the SDK’s own log lines use your format too. Hosts save a server’s stderr to a log file (Claude Desktop’s is mcp-server-kitebase.log), which is where you’ll debug:

2026-09-27 21:14:22,137 INFO kitebase: list_tickets took 1 ms

Log what you’ll need at 2 a.m.: which tool, which ticket, how long each call took, what failed. Not message text or customer data: log files get pasted into bug reports.

Timeouts on everything you call

before.py awaits Kitebase with no limit. When Kitebase takes 30 seconds, so does the tool call, while the user watches a spinner. Eventually the host gives up, and a message like “Timed out waiting for tools/call” tells the model nothing useful.

Put your own timeout, shorter than the host’s, on every call that leaves your process, so you get to write the error. server.py sends every Kitebase call through one helper:

async def call_kitebase(what: str, call, if_slow: str = "Try again in a minute."):
    """Run one Kitebase API call with a timeout, and log how long it took."""
    start = time.perf_counter()
    try:
        return await asyncio.wait_for(call, TIMEOUT_SECONDS)
    except asyncio.TimeoutError:
        log.warning("%s timed out after %.1fs", what, TIMEOUT_SECONDS)
        raise ToolError(f"Kitebase didn't answer within {TIMEOUT_SECONDS:g}s. {if_slow}")
    finally:
        log.info("%s took %.0f ms", what, (time.perf_counter() - start) * 1000)

Start with 5 seconds; a user is waiting. With a real HTTP client, set its timeout too (httpx.AsyncClient(timeout=5.0)).

The gotcha: a timeout means you stopped waiting, not it didn’t happen. If Kitebase sent the email before your 5 seconds ran out, it’s sent. That’s what if_slow is for, and the next habit.

Write tools that are safe to call twice

Retries happen whether you plan for them or not: the host times out, the model misreads a result, a network blip drops a response. For a read, a repeat costs a few tokens. For a write, it’s a second email to a customer.

A tool is idempotent when calling it twice with the same arguments has the same effect as calling it once. Here’s what a retry after a slow Kitebase does to each server:

Two ways to get there. Prefer set-style tools: assign_ticket sets the assignee to priya, and doing it twice leaves it priya. A toggle_status tool isn’t.

For writes that append, like sending a message, use an idempotency key: a string you send with the request so the API can recognize a repeat and return the first result instead of acting again. Stripe’s API works this way. Don’t ask the model for the key; it won’t reliably reuse one. Derive it from the arguments:

def reply_key(ticket_id: str, message: str) -> str:
    """Same ticket and same text give the same key, so a retry can't send twice."""
    return hashlib.sha256(f"{ticket_id}\n{message.strip()}".encode()).hexdigest()[:32]

A retry produces the same key, and Kitebase returns rpl_001 again. The timeout error tells the model so: “The reply may have been sent. Calling reply_to_customer again with the same message is safe: it won’t send a second email.”

If your API has no idempotency keys, look before you write: skip the send if an identical reply is already on the ticket. Real APIs also expire keys (Stripe may drop them after 24 hours), so the same “Any update?” next week still goes out.

Keep responses small

Everything a tool returns goes into the model’s context, and the host sends the whole conversation again with every later message. before.py returns what the API returns. For “Which tickets are about SSO?”:

search {"query": "sso"}              (before.py)   ~11,310 tokens, 5 full ticket records
search_tickets {"query": "sso"}      (server.py)   ~114 tokens, 3 five-field summaries

At claude-opus-5’s $5 per million input tokens, the first costs about $0.06 every time it’s sent. Worse, the five fields that matter are buried among internal ids, SLA settings, HTML copies of every comment and an audit trail. It also matched two tickets that only had “sso” in a tag.

Decide what the model needs and return only that, as a pydantic model so the shape is in the output schema:

def summary(raw: dict) -> TicketSummary:
    """Keep the five fields a model needs out of the raw API record."""
    return TicketSummary(id=raw["id"], title=raw["title"], status=raw["status"],
                         assignee=raw["assignee"], customer=raw["customer"]["name"])

get_ticket adds only the last 3 comments, cut to 300 characters, plus "comments_total": 12 so the model knows there’s more. KITE-144 goes from 2,244 tokens to 144. Default to caps like these and state them in the description. If users need more, add a narrower tool (get_ticket_comments(ticket_id, page)) rather than raising the cap for everyone.

Security basics

An MCP server gives a model hands. Three habits keep that from going wrong.

Least privilege

Whoever can steer the model can use every tool your server offers: the user, and, as the next section shows, anyone who can get text into a tool result. So give the server only the powers its tools need:

• Scope its credentials. The Kitebase token in the server’s environment should allow reading tickets, assigning and replying. Not deleting, not admin.
• Don’t expose what nobody asked for. The API has a delete endpoint; server.py has no delete_ticket.
• Narrow the targets. send_email(to, ...) can reach anyone. reply_to_customer(ticket_id, ...) can only reach the customer already on that ticket.

ToolAnnotations describe each tool’s behavior to the host (read_only_hint, destructive_hint, idempotent_hint, open_world_hint), which can use them to decide what to ask you about. They’re hints, not protection: the spec tells hosts to treat them as untrusted unless they trust the server.

Prompt injection through tool results

Prompt injection is text from an untrusted source that tries to act as instructions to the model (article 03 of AI Engineering introduced it with a support ticket). With MCP, it arrives through your own tools. Customers write ticket comments. get_ticket returns them. The model reads them in the same context as your user’s request. The last comment on KITE-143 is this:

There’s no reliable way to make a model ignore instructions it reads. So layer defenses:

• Limit the damage. This is the one that works. With before.py, a fooled model can email everything to an attacker’s address. With server.py, the worst it can do is reassign tickets (annoying, reversible) or reply to Blue Fern Labs.
• Label untrusted text. get_ticket returns {"author": "customer", "text": ...}, and its description says comment text is information, never instructions. This helps; it isn’t a guarantee.
• Keep a human on the writes. The spec says hosts should let a person deny tool calls and confirm sensitive ones. Mark reads read_only_hint=True, so a host can skip asking about those and confirm the rest. Guardrails and Human in the Loop goes further.

One gap stays open: reply_to_customer can still send Blue Fern Labs anything in the model’s context, including other customers’ tickets it looked up earlier. That’s why the user should approve each reply, seeing the message first.

Try it yourself

The companion example has both servers, the fake Kitebase API and a script that runs every request in this article against both.

Download the runnable example (zip)

cd 06-server-best-practices
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Then try these:

1. In server.py, change RECENT_COMMENTS = 3 to 50 and run main.py. The get_ticket result for KITE-143 roughly doubles to about 380 tokens, for a ticket with only 9 comments.
2. In reply_to_customer, pass idempotency_key=None to api.post_reply and run pytest -q. The test for a slow Kitebase now fails: the retry sends a second email.
3. In main.py, change the last bad-arguments call to {"ticket_id": "kite-144", "assignee": "priya"}. The schema’s pattern rejects the lowercase id. If you’d rather be forgiving, drop the pattern and normalize with .strip().upper() in each tool, as article 03 did.

pip install pytest && pytest -q runs the 12 offline tests. Two launch the servers over stdio, including one that catches before.py’s banner breaking the connection.

Common beginner mistakes

• Generic names. search and update collide with other servers’ tools and say nothing. Use search_tickets.
• A data: dict argument. The model gets a blank form and guesses the fields. Type every argument.
• Passing the API response straight through. Thousands of tokens per call, mostly noise. Pick the fields.
• print() for debugging. On stdio, stdout is the protocol. Use logging on stderr.
• Writes that aren’t safe to repeat. Retries are normal. Make writes set-style or send a key derived from the arguments.

Questions you will face in production

“How many tools is too many?” There’s no hard number, but every definition goes to the model on every request, and more similar tools mean more wrong picks. Start with the five to ten tasks users actually ask for. Needing many more often means two servers.

“Should destructive actions be tools at all?” Only when users need the model to do them. If a mistake is cheap to undo, a clearly named tool with destructive_hint=True and host confirmation is fine. If not (deleting data, moving money), leave it out, or have the tool stage the change for a human to approve in your app.

“How do I know my descriptions work?” Test the model’s choices, not just your code. Write 20 or so real requests with the tool you expect for each, run them against the Claude API with your tool list, and count the wrong picks. LLM Evaluation Pipelines shows how to build that check.

Check your understanding

What to remember

• The model picks tools from their names and descriptions alone. Use verb_noun names and say when to use a neighbor instead.
• Small, typed tools beat flexible ones. Validate in the schema first, then in code, and raise ToolError with what to do next.
• On stdio, stdout is the protocol. Log to stderr with logging.
• Put a timeout on every outside call, and make every write safe to repeat: set-style, or an idempotency key derived from the arguments.
• Return the few fields the model needs, capped, and say what the cap is.
• Assume every tool will be called by a model that’s been fooled. Least privilege limits what that costs.

What to study next

Your server is now worth connecting to something. Article 07: Connecting to Claude Desktop, Cursor, Etc. covers registering it with real hosts over stdio, running it over Streamable HTTP, and putting a login in front of it. If a tool misbehaves once it’s there, come back to the descriptions and errors sections here first.

Further reading

• MCP spec: Tools. Tool names, annotations, tool execution errors and the security considerations quoted above.
• MCP spec: Security best practices. The official guidance on consent, token handling and least privilege.
• MCP Python SDK. MCPServer, ToolError and ToolAnnotations, as used here.
• Stripe: Idempotent requests. A clear description of idempotency keys from an API that uses them.
• OWASP: Input validation cheat sheet. Why you validate at every boundary, applied here to tool arguments.

Where this article comes from. This is a synthesis of the MCP specification and common practice in AI engineering as of 2026, not a citation of any single paper. The sources above are where the mechanics come from. If you find an error or have a better source for a claim, the article gets fixed within a day, send me a note.