MCP vs API: what an MCP server adds to your API

Your API already works, and the docs explain how to use it, but now developers want to access it through AI agents like Claude or Cursor. How do you connect your API to those agents without building a custom integration for every AI client?

Model Context Protocol (MCP) is an open standard for connecting AI clients to tools and data. An MCP server puts your API on that standard, so developers can request data or actions in plain language from whichever client they use. Your team decides which operations agents can use, what data each tool returns, and whether agents can search your docs for answers.

MCP vs API: what's the difference?

An API lets software request data or actions from another application. An MCP server connects compatible AI clients to that API so that users can ask for the same things in plain language instead of code. In a typical API integration, your code decides which call to make. With MCP, the AI model picks the tool from the server's list based on the user's prompt.

Depending on the MCP tools the server provides, you can:

• Search docs and query databases
• Retrieve filtered data
• Ask the AI client to complete multi-step tasks across connected systems

Here's how the two compare across setup, discovery, data, and access:

	API	MCP server
What does it do?	Lets software request data or actions from another application	Gives compatible AI clients a standard way to access tools that retrieve data or perform actions
How does it connect to an AI client?	Developers build or configure an integration so the client can use the API	Developers connect the server's tools to the API, and compatible clients use those tools through MCP
How does the client know what it can do?	The integration defines which API operations the client can use	The client requests a list of tools, with descriptions and required inputs
What information comes back?	The API returns the data requested, with filtering where supported	The tool can return the API's response or selected fields
Does each AI client need a separate integration?	Separate integrations may be needed, depending on the clients	Compatible clients share the server's tools, though each still needs connection setup
What controls access?	The API checks credentials and permissions	Both the server and API need appropriate access controls

Once an AI client can discover available tools, your MCP server determines which API actions it can request and what data it receives.

What an MCP server adds to an API

An MCP server adds a discoverable set of tools for working with your API. Your team defines what agents can do and what information each tool returns, including answers from your docs. The same tools can serve multiple AI clients.

Runtime tool discovery

An MCP server adds runtime discovery to your API, letting AI clients find out which tools are available and how to call them.

Typically, without an MCP server, the developer building each AI application defines the available functions and writes the API integration code into it. With an MCP server, an AI client can connect to your server and send a tools/list request. The server returns a standardized list of available tools, each with a name, a plain-text description, and an input schema. When a user sends a prompt, the model checks that list, picks the tool that matches the request, formats the input according to the schema, and asks the server to run it.

Your team still builds the server and connects its tools to your API once. After that, new or updated tools reach every connected client without changes on their side.

A curated set of operations for agents

Your team chooses which API operations become MCP tools. Even if your underlying API supports full write access, you don't have to make every operation available to an AI client. A smaller set of clearly described tools also helps agents pick the right one and keeps tool definitions from crowding their context.

Starting with read-only tools lets agents retrieve information without modifying production data. GitHub's MCP server, for instance, lets developers enable specific toolsets or run in read-only mode, blocking write actions through that server.

An MCP server doesn't replace your API's security controls. A search tool still has to verify who is asking and what they're allowed to see. Two users might call the same search tool, but your system must ensure each person sees only data they're authorized to access.

Responses trimmed to what agents need

An MCP tool can return only the fields an agent needs, which helps the AI focus on the question and reduces the input tokens it processes. When an AI client calls a tool like get_order_status, the server fetches the record from your API and returns only the fields the tool is configured to include.

For example, a user might ask, "Has order 4821 shipped?" Without filtering, the MCP tool could return the full order record, including unrelated customer contact details and purchase information.

{
  "order_id": "4821",
  "status": "shipped",
  "created_at": "2026-10-14T09:32:11Z",
  "customer": {
    "name": "Jordan Lee",
    "email": "jordan.lee@example.com",
    "phone": "+1-555-0142"
  },
  "shipping_address": {
    "line1": "200 Market St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105"
  },
  "items": [
    { "sku": "KB-201", "quantity": 1, "price": 129 },
    { "sku": "CB-USB-C", "quantity": 2, "price": 12.5 }
  ],
  "payment": { "last4": "4242", "total": 154 },
  "shipment": {
    "carrier": "UPS",
    "tracking_url": "https://example.com/track/4821",
    "shipped_at": "2026-10-15T16:05:00Z"
  }
}

With filtering, the MCP tool can return only the necessary information: the order number, shipping status, and tracking URL.

{
  "order_id": "4821",
  "status": "shipped",
  "tracking_url": "https://example.com/track/4821"
}

MCP doesn't filter responses on its own, and APIs can filter too. You can build filtering directly into the MCP tool or use filters your API already supports.

Docs search without crawling

An MCP server with docs search gives agents direct access to your docs, letting them fetch the exact page or section they need instead of burning tokens crawling code or browsing web pages.

In a Mintlify customer experiment, agents using structured docs through MCP used roughly half as many tokens per task as agents exploring internal codebases with no docs. MCP tool definitions also take up context space, so include them when measuring token savings.

If a developer asks Cursor, "How do I authenticate requests to the orders endpoint?" an agent without connected docs might search repository files or the web for an example. With an MCP docs tool, the agent can search your docs for the required authentication header format and suggest a code change.

One integration for every AI client

A single MCP server lets Claude, Cursor, or an internal AI agent use your API without separate integrations for each platform. You write the tool logic once, and any compatible client can connect to it. When your API changes, you update one server instead of several client integrations. Each client still needs connection setup and authentication where required.

For example, without an MCP server, a new returns endpoint means a code change in each client integration your team maintains. With an MCP server, you add a create_return tool once and every connected client can find it the next time it lists tools.

How to decide what to expose through MCP

When deciding what to expose through your MCP server, weigh how useful each tool is against what happens if an agent calls it at the wrong time or with the wrong input. To find the right balance for your team, use your API usage data and developer feedback to work through these three steps:

1. Confirm you need an MCP server. An MCP server is helpful when AI clients need to choose tools dynamically based on user prompts. If your workflow just runs the same fixed API calls every time, a direct API connection may be simpler.

2. Start with a read-only task users regularly need. You might let users check an order's status, then test whether the tool returns only the necessary information and respects user access permissions.

3. Evaluate actions that modify data. Add frequently needed, low-risk actions first, such as creating support tickets. For higher-risk actions like refunds or account deletions, require confirmation before execution, or keep them off the server until you can enforce appropriate permissions and approval checks.

If you document your API with Mintlify, you get a hosted MCP server for your docs without building one, and you control which pages it can search.

Add an MCP server with Mintlify

Every Mintlify site comes with a hosted MCP server, generated from the same docs your developers read. There's no separate server to build or keep in sync by hand. Out of the box, the server comes with hosting, search tools, one-click setup, and controls over what agents can find.

A hosted server at /mcp. Mintlify hosts the server at the /mcp path of your docs site, such as docs.example.com/mcp. If your docs require login, a separate server at /authed/mcp returns only the content each signed-in user is allowed to see. Mintlify also serves a discovery document at /.well-known/mcp so that agents and tools can locate the server without extra setup.

Search, page reads, and feedback. The server gives agents three tools. Search finds relevant pages and can filter by version and language. A docs filesystem tool reads full pages as Markdown or pulls out a single section. A feedback tool lets agents report a docs problem, which shows up in your analytics.

One-click setup for developers. Add cursor and vscode to contextual.options in your docs.json, and the contextual menu on every page gets Connect to Cursor and Connect to VS Code options that install your hosted MCP server. Other menu options copy the server URL or an npx add-mcp install command for clients like Claude Code. For example, a developer at a customer company clicks Connect to Cursor on your docs. Later, when they need to paginate the orders endpoint, Cursor searches your docs and pulls the pagination section into the editor.

API reference from your OpenAPI spec. Mintlify generates API reference pages from your OpenAPI spec. Once those pages are in your navigation, the MCP server indexes them like any other page, so agents find endpoints and how-to content in one place.

Control what agents can find. By default, the server indexes the pages in your navigation. Add noindex: true to a page's frontmatter to keep it out of search, or set seo.indexing to "all" in docs.json to include hidden pages.

Docs that stay current. Autopilot is an always-on agent that watches your code and the systems around it for changes your docs don't cover yet. Then, when it spots a gap, it drafts the fix as a pull request for your team to review. For example, when your team merges a change to your API's authentication flow, Autopilot reads the diff, drafts updates to your authentication docs, and tags a reviewer to approve them before anything ships.

Frequently Asked Questions

Does MCP replace REST APIs?

It complements your API rather than replacing it. An MCP server acts as an adapter, translating an AI client's tool calls into requests to your existing API.

Can you generate an MCP server from an OpenAPI spec?

Yes. Tools like FastMCP can generate MCP servers from OpenAPI specs. You should still choose which operations to make available and filter unnecessary data from tool responses. FastMCP's own docs note that models perform better with curated MCP servers than with auto-converted OpenAPI servers, especially for large APIs.

Will an MCP server respect user permissions?

An MCP server respects user permissions only if it verifies who's calling and enforces what each user can see, and your API still needs its own controls. For docs, Mintlify's /authed/mcp server handles this for you. It searches only the content the signed-in user is allowed to see.

Does Mintlify provide a hosted MCP server that agents and IDEs can query?

Yes. Every Mintlify site has a hosted MCP server at the /mcp path of your docs site, which agents in Cursor, VS Code, Claude Code, and other MCP clients can query. For docs behind a login, a separate server at /authed/mcp returns only the content each user is allowed to see.

Can my team create and update docs from Claude or Cursor through Mintlify's MCP?

Yes, through the admin MCP server, which is separate from the search server your developers use. It gives AI tools write access to edit pages, update settings, and open pull requests, so treat it like any other tool with write access.