What I learned building partner-center-mcp
Building against the Partner Center REST API means living in Microsoft Learn. Microsoft archived the
Partner Center .NET SDK in June 2023 and points partners at the REST APIs, but the SDK still turns up in
search results, and so does code that requests tokens for the retired graph.windows.net audience and
gets a 401 with error 900420 back. A model trained on that material reproduces it with confidence.
partner-center-mcp is the MCP server I wrote to put the current documentation next to the agent instead. This post is about the decisions behind it, and what I would tell anyone designing an MCP server.
What it is
It is a knowledge and code generation assistant for the Partner Center REST API. Ask how to cancel a
subscription and it returns the verified method, path and headers, a code sample, the constraints the
documentation warns about, and the docUrl the answer was checked against.
The tools fall into a few groups. Some look things up: scenarios, enum values, resource fields, error
codes. Some generate: pc_generate_call emits a REST call in curl, C#, TypeScript or PowerShell, never
the archived SDK. Some lint: pc_check_auth flags retired auth patterns such as the graph.windows.net
audience and ADAL, and pc_validate_request checks a call against the known scenarios. pc_migrate_from_sdk
translates archived SDK code into the equivalent REST scenarios. A set of pc_plan_* tools return ordered
workflows, such as a New Commerce purchase or GDAP onboarding.
It runs with npx partner-center-mcp, over stdio by default, with an optional Streamable HTTP variant.
The same knowledge pack also ships as a .NET server on NuGet.
Decide what the server will never do
The most important decision was what to leave out. partner-center-mcp holds no credentials and never calls Partner Center. It reads a bundled knowledge pack and, as a fallback, searches Microsoft Learn.
That one decision removes most of the hard problems. There is no token to leak, no tenant to damage, and
no way for a prompt injection to turn into a purchase. Every tool can honestly be marked
readOnlyHint: true and destructiveHint: false.
The annotations are meant to describe the worst case, so the exceptions are declared as well:
pc_search_docs and pc_get_scenario with enrich: true reach the network, and pc_build_request mints
a fresh MS-RequestId on every call, so none of them claim to be idempotent and offline. The specification
tells clients to treat annotations as untrusted unless the server is trusted, so they are information
rather than a guarantee. That is all the more reason to keep them accurate.
My general advice: before choosing tools, write down what the server must never be able to do. The smallest server that is still useful is usually much smaller than the API it covers.
Narrow tools, and say which sibling to use
The server has close to thirty tools, each with one job. That is more than I would usually recommend, and
it has a cost: the model has to pick the right one. The descriptions carry that weight. Each says when to
use the tool and which sibling to prefer instead. This is the description of pc_lookup_error, shortened:
Look up a Partner Center error by its numeric code or HTTP status ...
Use this when you already have a clean code. If you have a raw error response,
pc_decode_error is better. For a symptom described in prose with no code at all,
use pc_diagnose. Read-only, offline, deterministic.
Every parameter has a description too, written for a reader who cannot ask questions: "Matched exactly, so
strip surrounding text first." Every tool also has a title and a declared outputSchema.
The general lesson is that a tool description is the whole contract. The model never sees your source. If two tools overlap, the description has to draw the line between them, or the model will draw it at random. I wrote more about this in designing tools an LLM can use correctly.
Ground answers in the documentation, not in model memory
The reason the server exists is that the model's memory is the problem. So answers come from data, not from the model.
The knowledge pack lives in data/ as JSON. Every file is validated against a zod schema at load time,
so malformed data fails at startup rather than in an answer. Every scenario carries the docUrl it was
verified against and the date it was last checked, and 185 of them ship the response example their Learn
page publishes, so field names can be read off rather than guessed.
When the pack has no answer, pc_search_docs queries Microsoft Learn. Successful results are cached for
ten minutes in a bounded cache. When the live search fails, the result comes back empty with a note
that says so and points back at the curated pack, rather than looking like a search that found nothing.
Its description also tells the model to try the verified, offline tools first.
A pack that nobody checks becomes one more stale memory, so verification is built in. npm run check-pack
runs offline on every pull request and compares each scenario's method, path and headers against a
committed snapshot of what the Learn pages say. npm run check-docs runs weekly in GitHub Actions,
re-fetches every referenced page, and opens an issue when a page is moved, removed or changes a field the
pack depends on.
Grounding is not a feature you add once; it is a maintenance commitment. If you ground a server in documents, plan for how you will know when the documents change.
Errors the model can act on
Every tool answers with the same envelope: { ok, data } on success, { ok: false, error, suggestions? }
on failure. A miss is never a guess. An unknown scenario id comes back with suggestions listing close or
valid ids, and a linter finding carries a fix:
{
"ok": false,
"findings": [
{
"severity": "error",
"message": "Path matches a known scenario but the method POST is wrong; expected GET.",
"fix": "Use GET for /v1/customers/{customer-id}/subscriptions."
}
]
}
An error message for a model should do the same job as one for a junior developer: say what was wrong
and what a correct input looks like. If you are starting from scratch, the specification's isError flag
on a tool result exists for exactly these failures, and clients are expected to pass such results to the
model so it can correct itself. partner-center-mcp signals failure inside its envelope instead, which its
outputSchema describes.
Declare the output, then test it over the wire
Declaring an outputSchema is a promise the SDK enforces: it validates every tool's structured content
before returning it, so a schema that disagrees with the real payload turns a working tool into an error
at call time. The repository tests that path end to end. One suite starts the HTTP server and calls every
tool over the real transport with the real knowledge pack, including the not-found path. A comment in that
test records that the not-found path is the one that broke clients before suggestions was declared in
the schema.
Unit tests are not enough for an MCP server, because the consumer is a model. The repository has two more
layers. npm run eval runs a deterministic golden-case suite, for example asserting that generated code
contains the token helper and never mentions graph.windows.net. npm run eval:llm gives a real model
the tool names and descriptions with a natural-language question and checks that it picks one of the
expected tools. That second suite is the only test that tells you whether your descriptions work.
HTTP is a different threat model
Over stdio, only the process that started the server can talk to it. The Streamable HTTP variant is
another matter: it is a web server. It has no authentication of its own, so it binds to 127.0.0.1 by
default, caps request bodies at 1 MiB, and rejects a browser Origin that is neither loopback nor
explicitly allowed. That last check is what keeps a random web page from driving a local server, and the
specification requires servers to validate Origin for the same reason.
If your server can run over HTTP, treat that mode as a separate product with its own threat model.
Try it
claude mcp add partner-center -- npx -y partner-center-mcp
The README has the configuration for VS Code, Visual Studio, Cursor and the other hosts. It is an unofficial community project, not affiliated with Microsoft. New scenarios and documentation fixes are welcome on GitHub.
