devLap

What to Do When an API Has Too Many Endpoints for One MCP Server

dev.to

Large APIs are where MCP design gets interesting.

If your API has 15 endpoints, you can review each one by hand and decide which operations should become tools. If your API has 300 endpoints, exposing everything creates a different problem:

the MCP server becomes technically complete but hard for an AI client to use.

An AI client does not see your product the way your backend team sees it. It sees a list of tool names, descriptions, and input schemas. If that list is too large or too repetitive, the client has to spend more effort choosing a tool than solving the user's request.

The fix is not to dump the whole API into one MCP server. The fix is to design focused capability surfaces.

Why too many endpoints become too many tools

Most APIs grow around product history.

You may have:

  • old routes kept for backward compatibility
  • admin-only routes
  • internal debugging routes
  • several versions of similar endpoints
  • narrowly scoped CRUD routes
  • bulk import and export routes
  • billing routes
  • account-management routes
  • support and reporting routes
  • endpoints created for specific frontend screens

That API shape may be fine for developers. It is not automatically a good AI-facing interface.

If you convert every endpoint into one MCP tool, the client may see dozens of similar options:

get_customer
get_customer_by_id
fetch_customer
list_customers
search_customers
admin_get_customer
get_customer_summary
get_customer_details
Enter fullscreen mode Exit fullscreen mode

Even if each tool works, the set becomes noisy. The model has to infer which tool is safest, which one returns the right fields, and which one matches the user's intent.

That extra ambiguity leads to wrong calls, more retries, slower workflows, and harder debugging.

Group endpoints by user workflow

The first reduction pass should be workflow-based.

Do not start with:

"Which endpoints do we have?"

Start with:

"Which user task should this MCP server help with?"

For example, a SaaS product may have several possible workflow groups:

  • customer support context
  • sales account research
  • billing and invoice lookup
  • project management updates
  • workspace administration
  • analytics reporting
  • developer operations

Each group needs a different tool surface.

A support workflow might need:

get_customer
list_customer_tickets
get_ticket
list_customer_subscriptions
Enter fullscreen mode Exit fullscreen mode

It probably does not need:

delete_customer
create_invoice_adjustment
rotate_api_key
update_workspace_permissions
run_internal_report
Enter fullscreen mode Exit fullscreen mode

Grouping by workflow helps you remove endpoints without arguing about whether they are "important." Many endpoints are important to the product, but irrelevant to a specific AI workflow.

Create focused MCP servers instead of one giant server

For a large API, one MCP server can become a junk drawer.

Focused servers are easier to reason about.

For example:

Support MCP server
- get_customer
- list_customer_tickets
- get_ticket
- create_ticket_note

Billing MCP server
- list_customer_invoices
- get_invoice
- get_subscription

Admin MCP server
- get_workspace_settings
- update_workspace_setting
Enter fullscreen mode Exit fullscreen mode

These do not have to be separate products. They are separate AI-facing surfaces.

The advantages are practical:

  • fewer tools per client connection
  • cleaner descriptions
  • simpler permission review
  • easier testing
  • clearer logs
  • safer rollout
  • less chance that an agent chooses an unrelated admin or billing action

This is especially useful when different roles should have different access. A support agent, sales rep, billing admin, and internal developer should not always see the same MCP tools.

Remove tools that do not map to a user intent

Some endpoints exist because the frontend or backend needs them. That does not mean an AI agent needs them.

Good MCP tools usually map to user requests like:

  • "Find this customer's open tickets."
  • "Show the latest invoice."
  • "Create a ticket from this report."
  • "Update the status to resolved."
  • "Summarize recent account activity."

Weak MCP tools often map to implementation details:

  • "Call endpoint v2."
  • "Patch object."
  • "Run admin action."
  • "Submit generic payload."
  • "Fetch raw config."

When reviewing a large API, ask this for each endpoint:

What would a real user ask that should cause an AI client to call this tool?

If you cannot write that request clearly, leave the endpoint out for now.

Merge or rename confusing duplicates

Large APIs often contain overlapping endpoints.

For example:

GET /customers/{id}
GET /customers/{customer_id}/profile
GET /crm/customers/{id}
GET /support/customers/{id}
Enter fullscreen mode Exit fullscreen mode

These might serve different backend needs, but they can create confusing MCP tools:

get_customer
get_customer_profile
get_crm_customer
get_support_customer
Enter fullscreen mode Exit fullscreen mode

If the agent's task is support context, expose the one that returns the right support-facing shape. Do not expose all four unless the differences are clear and necessary.

If two tools must remain, name them by user-visible purpose:

get_customer_support_profile
get_customer_sales_profile
Enter fullscreen mode Exit fullscreen mode

That is better than making the model guess the difference between crm and support from internal naming.

Reduce schema complexity

Tool overload can come from the number of tools, and it can also come from one huge schema.

Watch for tools that accept:

  • arbitrary JSON blobs
  • many unrelated optional fields
  • broad filter objects
  • raw query strings
  • generic data payloads
  • fields whose meaning depends on another hidden field

This kind of schema makes the AI client guess how to construct a safe request.

Instead of one giant update tool:

update_customer
Enter fullscreen mode Exit fullscreen mode

Consider smaller tools:

update_customer_billing_email
update_customer_support_status
update_customer_account_owner
Enter fullscreen mode Exit fullscreen mode

The smaller tools are easier to describe, easier to permission, and easier to test.

There is a tradeoff. Too many tiny tools can also become noisy. The line I use is simple: split a tool when the actions have different permissions, side effects, or user intent.

Treat sensitive operations as a separate surface

Some endpoints should not be mixed into a general-purpose MCP server.

Review these carefully:

  • deletes
  • bulk updates
  • exports
  • billing changes
  • permission changes
  • API key creation
  • OAuth client management
  • account cancellation
  • admin impersonation
  • internal maintenance tasks
  • notification or message sending

These operations are not forbidden forever. They need stronger review.

For sensitive tools, define:

  • who can call the tool
  • which credential scope is required
  • whether a confirmation step is needed
  • what records can be touched
  • whether the action can be reversed
  • how the action appears in logs
  • how to test unauthorized calls
  • how to roll back mistakes

If a sensitive endpoint is useful only to internal staff, do not expose it in the same MCP server used by customers.

Improve descriptions before adding more tools

When an AI client chooses a tool, the description does real work.

For a large API, weak descriptions compound fast.

Bad:

Gets customer.
Enter fullscreen mode Exit fullscreen mode

Better:

Get the support-facing profile for one customer by customer ID. Use this before checking tickets or subscription status.
Enter fullscreen mode Exit fullscreen mode

Bad:

Updates ticket.
Enter fullscreen mode Exit fullscreen mode

Better:

Change the status of one support ticket after the user confirms the new status.
Enter fullscreen mode Exit fullscreen mode

Descriptions should answer:

  • when to use the tool
  • what input is needed
  • what the tool returns
  • whether the tool changes data
  • whether the tool has side effects
  • when another tool is a better fit

If you have 40 tools with vague descriptions, adding 20 more tools makes the system worse. Fix the existing tool interface first.

Use an allowlist, not a denylist

For large APIs, I prefer an allowlist.

A denylist says:

"Expose everything except these dangerous routes."

That is risky because new endpoints may appear later and slip into the MCP surface by default.

An allowlist says:

"Expose only these selected operations."

That is safer and easier to review.

A simple allowlist can look like:

servers:
  support_context:
    expose:
      - GET /v1/customers/{customer_id}
      - GET /v1/tickets
      - GET /v1/tickets/{ticket_id}
      - POST /v1/tickets/{ticket_id}/notes

  billing_lookup:
    expose:
      - GET /v1/invoices
      - GET /v1/invoices/{invoice_id}
      - GET /v1/subscriptions/{subscription_id}

  admin_controls:
    expose:
      - GET /v1/workspaces/{workspace_id}/settings
      - PATCH /v1/workspaces/{workspace_id}/settings
Enter fullscreen mode Exit fullscreen mode

This makes the decision explicit. It also makes reviews cleaner when the API changes.

Test the tool set as a set

Testing each tool by itself is necessary, but it is not enough.

When the API is large, you also need to test tool selection.

Use prompts that resemble real user requests:

Find open tickets for customer cus_123.
Enter fullscreen mode Exit fullscreen mode 
Show the latest unpaid invoice for customer cus_123.
Enter fullscreen mode Exit fullscreen mode 
Update ticket tick_456 to resolved.
Enter fullscreen mode Exit fullscreen mode 
Can you delete this customer?
Enter fullscreen mode Exit fullscreen mode

Then check:

  • Does the client choose the expected tool?
  • Does it confuse similar tools?
  • Does it ask for missing IDs?
  • Does it avoid high-risk actions without confirmation?
  • Does it handle permission errors clearly?
  • Does it recover from empty results?
  • Does the server log show the tool name, status, latency, and response size?

If the agent keeps choosing the wrong tool, do not patch around it only with prompts. Reduce the tool set, rename tools, improve descriptions, or split the server by workflow.

How 0mcp helps with large APIs

With 0mcp, teams can import a supported Swagger, OpenAPI, or Postman definition, review detected operations, and select which API functions should become MCP capabilities.

That selection step matters for large APIs. The point is not to publish every route. The point is to choose the useful operations, refine names and descriptions, test the result in the Playground, and host the selected server over Streamable HTTP.

0mcp currently supports hosted Streamable HTTP servers, not local stdio servers. Existing API authentication continues to be used through API key, Bearer token, or OAuth pass-through. The original API still owns business logic, authorization, tenant boundaries, pagination, rate limits, and validation.

That division is important. A hosted MCP workflow can make selection, hosting, testing, logs, analytics, and version management easier. It should not replace your product's permission model.

For a deeper website guide on endpoint selection, see how to choose which API endpoints to expose as MCP tools.

Source: dev.to

arrow_back Back to News