Skip to main content

What I learned building partner-center-mcp

· 8 min read

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.