How to build an SEO MCP server that earns its runtime

The single biggest MCP mistake is building a server for no workflow in particular. That server ends up with too many tools, vague output, and no obvious boundary for retries or permissions.

Write one sentence that names the workflow. Example: A growth engineer in Claude Code wants to compare one target page with the US desktop SERP and leave with an approved refresh brief.

That sentence gives you an inclusion test. A tool belongs only when it helps the user complete that job. Keyword metrics, SERP evidence, and a refresh brief may belong. A generic browser, CMS publish action, and backlink crawler probably do not belong in the first release.

The two shapes that hold up are the thin wrapper and the workflow router. Pick one on purpose, then make the permission and error boundary visible.

The model reads tool definitions while deciding what to call. A tool description is part of the interface, not annotation after the fact. It should say what the tool does, when to use it, the important limit, and what a successful response contains.

There is no magic maximum number of tools or arguments. The practical boundary is whether a model can select the right tool from a real user request without guessing at hidden provider vocabulary. Split tools when the input contract or the downstream decision changes; keep them together when the same evidence answers the same question.

For a page-refresh workflow, three tools are enough to learn whether the MCP boundary is earning its runtime. The first gets the search evidence. The second compares a known page with that evidence. The third turns an approved finding into a bounded brief. Add a fourth tool only when a real task shows a missing decision.

The SDK changed quickly, so check the current official quickstart before copying an older import path. As of September 17, 2026, the current v2 documentation uses `@modelcontextprotocol/server`, Zod 4, a server factory, and separate transport helpers. The AgentSEO npm package still uses the v1 `@modelcontextprotocol/sdk` line. Both can work; do not mix their imports inside one server. Use v2 for a new build, or finish a deliberate migration with the official guide.

This compact v2 example shows the shape. It keeps the tool description specific, validates the keyword and location before the handler runs, returns both readable text and structured content, and writes no protocol-breaking logs to stdout.

Use stdio when the MCP host launches a local child process. It is a clean first build because there is no remote server to operate, and the local environment can supply the upstream API key. Keep protocol messages on stdout; use stderr for logs and failures.

Use Streamable HTTP when multiple users or remote clients need one managed endpoint. Then the server owns authentication, authorization, rate limits, audit logs, and upstream credentials. The current MCP guidance recommends Streamable HTTP for remote servers and treats the older HTTP plus SSE path as backwards compatibility.

Do not create an auth tool that asks the model to handle credentials. Give the client a configured authentication path, expose only the permissions the workflow needs, and make write actions visibly separate from read-only research.

Every tool output should include a compact summary, evidence, and a suggested next action. This lets the model act without inventing a parsing layer. For long-running SEO work, add job state, the safe polling method, and the condition that makes the job terminal.

An eval set is what keeps the server honest. Start with ten prompts a real user would type. Run them through the real transport. Log pass or fail per prompt, the selected tool, the returned error shape, and whether the answer led to the right next step.

Rerun the set on every tool, schema, or transport change. If a prompt breaks, investigate the tool and its description before weakening the eval.

These mistakes are easy to avoid if you name the decision boundary early.

On July 20, 2026, we smoke-tested AgentSEO MCP server version 0.1.2 over stdio using protocol 2024-11-05. The run covered initialization, tools/list, schema presence, invalid parameters, unknown tools, bad credentials, missing credentials, and a real prompt-to-decision path.

The useful result was not the pass count. The run exposed one design warning: 43 of 45 tool descriptions did not tell the model that the underlying work could be asynchronous. The agent completed the task in 18.4 seconds with one extra call, but the missing async cue made polling behavior less predictable. That is the kind of failure a handler-only unit test will not reveal.

The test did not measure every host, production load, customer data quality, or model's planning ability. It did give us a practical release gate: test initialization, discovery, invalid arguments, credentials, and one complete user decision through the transport people actually use.