Quick answer: A Model Context Protocol (MCP) server exposes an API's operations as tools that an AI agent can discover and call, with a typed input schema and a result the model can act on. For an existing HTTP API, the fastest reliable path is to build the MCP server from the OpenAPI contract rather than hand-writing tool wrappers, so the tools cannot drift from the real API. The hard parts are not the happy path — they are transport, authentication, least-privilege scoping, and versioning tools without breaking the agents that depend on them.

This guide walks the full lifecycle: turning a spec into tools, choosing where the server runs, securing it, testing it, and deciding when a hosted gateway beats a process you operate. Follow the links for concrete setups.

What MCP is and how it differs from function calling

MCP is a standard protocol for connecting an AI model to external tools and data, rather than hard-coding each tool into the application. If you are deciding whether to use it, start with MCP vs function calling vs plugins, and understand the three things a server can expose in tools vs resources vs prompts. The distinction between agents talking to each other and agents calling tools is in A2A vs MCP: agents vs tools.

Build an MCP server from OpenAPI

Hand-writing a wrapper per operation is slow and drifts the moment the API changes. The repeatable path is to generate the server from the contract: follow OpenAPI to MCP server step by step, the direct mapping in turn a REST API into an MCP server, and the hosted variant in OpenAPI to a hosted MCP server. Treat the server as a build artifact, not a project to maintain by hand; an MCP server is a build artifact explains the workflow.

Expose the right tools, not the whole API

Dumping every endpoint into a server wastes the model's limited context and invites calls the agent should never make. Scope the surface deliberately: expose three operations, not the whole OpenAPI, organize by agent with a hub that exposes per agent, not everything, and understand the cost of over-exposure in an MCP server wasting agent context. When the contract changes, the tool list must change with it; a spec change should update the MCP tool list.

Transport: stdio vs remote HTTP

A local stdio server is simple for a single user on one machine; a remote HTTP server is required when tools are shared, run in the browser, or need central auth. The comparison is in MCP stdio vs remote HTTP transports, and for shared or multi-user tools the recommendation is streamable HTTP beats stdio for shared tools.

Authentication and where tokens live

Remote servers need real auth, and credentials should never be embedded in prompts or tool payloads. Start with MCP authentication with OAuth2 for remote servers, keep the upstream token in the gateway rather than the MCP JSON in upstream token in the gateway, not in MCP JSON, and pin the base URL centrally with pin the base URL in the gateway, not the agent prompt.

Security: least privilege and prompt injection

Every tool you expose is a new path for an agent to act on your systems, so scope it tightly and assume tool output can contain hostile instructions. The threat model is in MCP security, prompt injection, and least privilege, and keys should be scoped per role rather than shared team-wide in scope MCP keys per role, not team-wide. You also need to be able to revoke a single teammate's key without rotating the whole URL; revoke one teammate key, not the whole MCP URL.

When a hosted gateway beats a server you run

For internal APIs and multiple upstreams, a gateway aggregates services, handles auth and rate limits, and keeps agents out of your network topology. The aggregation pattern is in an MCP gateway for internal APIs and aggregation, and the case for not operating a Node process yourself is in a hosted MCP gateway, not a Node server.

Versioning tools without breaking agents

Agents discover tools at runtime and depend on their input shapes, so renaming a tool or tightening a parameter can silently break a workflow. The safe approach is in versioning MCP tools without breaking agents.

Test, debug, and connect clients

Verify a server the same way you verify an API: list tools, call them with documented inputs, and check the results. The procedure is in how to test and debug an MCP server. Then connect the clients you actually use — connect Cursor and Claude Code to internal APIs, and compare the client landscape in MCP clients compared: Claude Desktop, Cursor, VS Code, Windsurf, Cline, Zed. When you publish, put docs and the server on a domain you control; publish API docs and MCP on a custom domain.

Where to go next

The MCP server is only as good as the contract behind it; return to the OpenAPI guide, and learn how to give agents the right context and verify their work in the AI coding agent guide.

FAQ

Do I need to write a new MCP server for every API? No — generate each from its OpenAPI document, and use a gateway to aggregate them. Hand-written servers are the exception, not the rule.

Is MCP only for AI coding assistants? It started there, but it is a general way to give any compatible model controlled access to tools and data, including internal enterprise systems.

How do I stop an agent calling a dangerous tool? Don't expose it, scope keys to the minimum role, and enforce authorization on the upstream service as if the MCP layer were untrusted. Prompt injection can arrive through tool results, so never rely on the model to self-restrain.