{"slug": "what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server", "title": "What to Do When an API Has Too Many Endpoints for One MCP Server", "summary": "A developer outlines a strategy for splitting large APIs across multiple focused MCP servers rather than exposing hundreds of endpoints through a single server. The approach groups tools by user workflow—such as support, billing, and admin surfaces—so AI clients face less ambiguity when selecting tools. The developer argues that endpoints should only become MCP tools when a clear user request maps to them, and that overlapping endpoints should be consolidated or named by user-visible purpose.", "body_md": "Large APIs are where MCP design gets interesting.\n\nIf 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:\n\nthe MCP server becomes technically complete but hard for an AI client to use.\n\nAn 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.\n\nThe fix is not to dump the whole API into one MCP server. The fix is to design focused capability surfaces.\n\nMost APIs grow around product history.\n\nYou may have:\n\nThat API shape may be fine for developers. It is not automatically a good AI-facing interface.\n\nIf you convert every endpoint into one MCP tool, the client may see dozens of similar options:\n\n```\nget_customer\nget_customer_by_id\nfetch_customer\nlist_customers\nsearch_customers\nadmin_get_customer\nget_customer_summary\nget_customer_details\n```\n\nEven 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.\n\nThat extra ambiguity leads to wrong calls, more retries, slower workflows, and harder debugging.\n\nThe first reduction pass should be workflow-based.\n\nDo not start with:\n\n\"Which endpoints do we have?\"\n\nStart with:\n\n\"Which user task should this MCP server help with?\"\n\nFor example, a SaaS product may have several possible workflow groups:\n\nEach group needs a different tool surface.\n\nA support workflow might need:\n\n```\nget_customer\nlist_customer_tickets\nget_ticket\nlist_customer_subscriptions\n```\n\nIt probably does not need:\n\n```\ndelete_customer\ncreate_invoice_adjustment\nrotate_api_key\nupdate_workspace_permissions\nrun_internal_report\n```\n\nGrouping 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.\n\nFor a large API, one MCP server can become a junk drawer.\n\nFocused servers are easier to reason about.\n\nFor example:\n\n```\nSupport MCP server\n- get_customer\n- list_customer_tickets\n- get_ticket\n- create_ticket_note\n\nBilling MCP server\n- list_customer_invoices\n- get_invoice\n- get_subscription\n\nAdmin MCP server\n- get_workspace_settings\n- update_workspace_setting\n```\n\nThese do not have to be separate products. They are separate AI-facing surfaces.\n\nThe advantages are practical:\n\nThis 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.\n\nSome endpoints exist because the frontend or backend needs them. That does not mean an AI agent needs them.\n\nGood MCP tools usually map to user requests like:\n\nWeak MCP tools often map to implementation details:\n\nWhen reviewing a large API, ask this for each endpoint:\n\nWhat would a real user ask that should cause an AI client to call this tool?\n\nIf you cannot write that request clearly, leave the endpoint out for now.\n\nLarge APIs often contain overlapping endpoints.\n\n```\nGET /customers/{id}\nGET /customers/{customer_id}/profile\nGET /crm/customers/{id}\nGET /support/customers/{id}\n```\n\nThese might serve different backend needs, but they can create confusing MCP tools:\n\n```\nget_customer\nget_customer_profile\nget_crm_customer\nget_support_customer\n```\n\nIf 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.\n\nIf two tools must remain, name them by user-visible purpose:\n\n```\nget_customer_support_profile\nget_customer_sales_profile\n```\n\nThat is better than making the model guess the difference between `crm` and `support` from internal naming.\n\nTool overload can come from the number of tools, and it can also come from one huge schema.\n\nWatch for tools that accept:\n\n`data` payloads\nThis kind of schema makes the AI client guess how to construct a safe request.\n\nInstead of one giant update tool:\n\n```\nupdate_customer\n```\n\nConsider smaller tools:\n\n```\nupdate_customer_billing_email\nupdate_customer_support_status\nupdate_customer_account_owner\n```\n\nThe smaller tools are easier to describe, easier to permission, and easier to test.\n\nThere 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.\n\nSome endpoints should not be mixed into a general-purpose MCP server.\n\nReview these carefully:\n\nThese operations are not forbidden forever. They need stronger review.\n\nFor sensitive tools, define:\n\nIf a sensitive endpoint is useful only to internal staff, do not expose it in the same MCP server used by customers.\n\nWhen an AI client chooses a tool, the description does real work.\n\nFor a large API, weak descriptions compound fast.\n\nBad:\n\n```\nGets customer.\n```\n\nBetter:\n\n```\nGet the support-facing profile for one customer by customer ID. Use this before checking tickets or subscription status.\nUpdates ticket.\nChange the status of one support ticket after the user confirms the new status.\n```\n\nDescriptions should answer:\n\nIf you have 40 tools with vague descriptions, adding 20 more tools makes the system worse. Fix the existing tool interface first.\n\nFor large APIs, I prefer an allowlist.\n\nA denylist says:\n\n\"Expose everything except these dangerous routes.\"\n\nThat is risky because new endpoints may appear later and slip into the MCP surface by default.\n\nAn allowlist says:\n\n\"Expose only these selected operations.\"\n\nThat is safer and easier to review.\n\nA simple allowlist can look like:\n\n```\nservers:\n  support_context:\n    expose:\n      - GET /v1/customers/{customer_id}\n      - GET /v1/tickets\n      - GET /v1/tickets/{ticket_id}\n      - POST /v1/tickets/{ticket_id}/notes\n\n  billing_lookup:\n    expose:\n      - GET /v1/invoices\n      - GET /v1/invoices/{invoice_id}\n      - GET /v1/subscriptions/{subscription_id}\n\n  admin_controls:\n    expose:\n      - GET /v1/workspaces/{workspace_id}/settings\n      - PATCH /v1/workspaces/{workspace_id}/settings\n```\n\nThis makes the decision explicit. It also makes reviews cleaner when the API changes.\n\nTesting each tool by itself is necessary, but it is not enough.\n\nWhen the API is large, you also need to test tool selection.\n\nUse prompts that resemble real user requests:\n\n```\nFind open tickets for customer cus_123.\nShow the latest unpaid invoice for customer cus_123.\nUpdate ticket tick_456 to resolved.\nCan you delete this customer?\n```\n\nThen check:\n\nIf 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.\n\nWith [0mcp](https://0mcp.io/), teams can import a supported Swagger, OpenAPI, or Postman definition, review detected operations, and select which API functions should become MCP capabilities.\n\nThat 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.\n\n0mcp 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.\n\nThat 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.\n\nFor a deeper website guide on endpoint selection, see [how to choose which API endpoints to expose as MCP tools](https://0mcp.io/blog/choose-api-endpoints-for-mcp?utm_source=devto).", "url": "https://wpnews.pro/news/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server", "canonical_source": "https://dev.to/bhavyshekhaliya/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server-1a77", "published_at": "2026-09-13 12:59:57+00:00", "updated_at": "2026-09-13 13:09:46.016023+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "ai-products"], "entities": ["MCP"], "alternates": {"html": "https://wpnews.pro/news/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server", "markdown": "https://wpnews.pro/news/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server.md", "text": "https://wpnews.pro/news/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server.txt", "jsonld": "https://wpnews.pro/news/what-to-do-when-an-api-has-too-many-endpoints-for-one-mcp-server.jsonld"}}