OpenAPI endpoint curation for MCP: expose the workflow, not the schema

Most teams building an MCP server for their SaaS product make the same first move: they point a generator at their OpenAPI spec and turn every endpoint into a tool. It ships fast. It also fails fast. The agent gets confused between POST /users, POST /v2/users, and POST /admin/users. It picks the wrong pagination endpoint. It calls the internal-only debug route because the description sounded relevant.

Endpoint curation isn't a nice-to-have step before you expose an MCP server. It's the work. The OpenAPI spec is a design-time contract for human developers reading docs. The MCP tool surface is a runtime menu an agent picks from mid-reasoning. Those are different jobs, and one-to-one mapping between them is where agent projects quietly go wrong.

The 1:1 mapping trap

An OpenAPI spec is a complete inventory. It lists every endpoint your API exposes — including the ones that exist for internal admin tooling, the ones kept for backwards compatibility, and the ones a partner team added last year that nobody's sure is still used. That's fine for documentation. It's a disaster for tool selection.

We've written before about how many tools an agent should have and why the ceiling is lower than the context window suggests. The short version: selection accuracy degrades well before you hit the token limit. Once you cross roughly 30–50 tools, the model starts picking wrong tools that look plausible — a threshold Anthropic's own guidance points to, though some models and workloads degrade earlier (OpenAI's guidance suggests staying under 20, and benchmarks like BFCL show accuracy dropping well before 50). A generator that turns 400 endpoints into 400 tools has already lost.

And the loss isn't uniform. The failure mode is specifically that near-duplicates — three different list_users variants, two overlapping search endpoints, a create_order and a create_order_v2 — become indistinguishable to the model. It picks whichever description happened to match the query slightly better. Sometimes that's the deprecated one. Sometimes that's the internal one.

Curation is a product decision, not a filter

The instinct is to reach for a mechanical filter: hide endpoints tagged internal, drop anything marked deprecated, exclude admin routes. That's necessary but not sufficient. What's left is still the developer-facing API, and the developer-facing API isn't shaped like the workflows an agent needs to complete.

A developer building an integration composes a workflow themselves. They call GET /customers, then GET /customers/{id}/subscriptions, then POST /subscriptions/{id}/cancel, and they read the docs between each step to figure out what fields to pass. An agent shouldn't have to do that. Every extra tool call is a fresh chance for the model to pick wrong, misread a response, or blow the context budget.

The better question isn't "which of my endpoints do I expose?" It's "what does the agent actually need to accomplish, and what's the smallest tool surface that lets it do that?" That's tool granularity more than endpoint filtering — sometimes the right MCP tool composes three REST calls behind a single interface.

Use tags as intent, not as inventory

OpenAPI tags are usually treated as documentation grouping. For MCP curation, they're the closest thing you have to a shipped signal of what an endpoint is for. Endpoints tagged admin, internal, experimental, or webhooks almost never belong on an agent's tool surface. Endpoints tagged with a business domain (billing, contacts, deals) are candidates — but candidates, not automatic includes.

A cleaner discipline: introduce explicit MCP-scoped tags. Something like x-mcp-expose: true on the endpoints you've decided are agent-appropriate, paired with an x-mcp-tool-name and a description written for a model rather than a developer. (These field names are illustrative — there's no official MCP/OpenAPI standard here, and existing generators use varying vendor-extension namespaces like x-mcp, x-mcp-tool-name, or x-speakeasy-mcp. Pick whichever your generator supports.) Now the generator has an allowlist expressed in the spec itself, versioned alongside the API. When someone adds a new endpoint, the default is that agents don't see it until a human decides they should.

This matters more than it sounds. Without an explicit allowlist, every new endpoint your team ships silently expands your agent's tool surface, and every new endpoint is a fresh selection-accuracy risk you didn't sign off on.

Design for the failure mode

Curation also means writing tool descriptions for the model, not for the OpenAPI viewer. We covered this in how to write tool descriptions for LLM agents, but the curation implication is specific: if two candidate endpoints would need near-identical descriptions to distinguish, one of them shouldn't be a tool. Merge them, drop one, or wrap them in a higher-level tool with a parameter that selects behaviour.

The same test works for parameters. If a required field only makes sense to someone who's read your internal architecture docs, the endpoint isn't ready to be a tool. Either the tool wraps it with sane defaults, or the endpoint stays off the surface until someone does that work.

How Pontil fits

Curation is a product decision, but it's also a maintenance problem. The allowlist you ship on Monday drifts by Friday: a new endpoint lands, an old one changes shape, a tag gets renamed. If the MCP surface isn't wired into the same SDLC as the API it exposes, the drift shows up as agent failures in production.

Pontil is a Tools-as-a-Service platform that generates and maintains the tool layer against the APIs you already have. Curation signals — MCP-scoped tags, tool names, description overrides — live in your codebase alongside the endpoints they annotate, and the generated tool surface stays in sync as the API changes. The runtime executes tools as the authenticated user, so the curated surface holds under real permissions rather than a shared service account. It's how the endpoint decisions you make today keep meaning what you meant a quarter from now.

What this changes

Stop treating MCP tool generation as a build step and start treating it as a product surface. The OpenAPI spec is one input. The other input is a deliberate answer to what your agent should be able to do — expressed in the spec through explicit MCP tags, curated descriptions, and a tool count that respects selection accuracy rather than fighting it.

If you're about to run a generator across your whole spec: don't. Pick the ten workflows agents actually need, work backwards to the endpoints that support them, and expose those. Everything else waits. The teams whose agents work in production aren't the ones with the most tools. They're the ones who made the hardest cuts.