MCP vs REST API: How to Choose (and When to Run Both)

Ask whether MCP or a REST API is the better choice and the honest answer is that they answer different questions. A REST endpoint answers how do I perform this operation. An MCP tool answers that too, but it first answers what operations exist here, and which one matches what the user just asked for. The second question has no place to live in a REST contract. OpenAPI describes shapes; it does not travel to the caller at runtime and it does not explain intent.

So the deciding question is not which protocol is more modern. It is who is holding the contract at the moment the call is made. If that is code you wrote, compiled, and deployed, the contract was read months ago by a human and REST is the right shape. If that is a language model choosing an action mid-conversation, the contract has to be readable, short, and delivered over the wire at connect time — which is what the Model Context Protocol standardises: JSON-RPC 2.0 messages, a capability handshake, and a uniform call convention across clients that implement the protocol.

A common production shape is both at once, with a small MCP server translating for agents while an existing HTTP service keeps serving the frontend, partners, and scheduled work. This page works through the mechanics of that split: the handshake REST never had, a wire-level trace of a livestream job through both interfaces, what changes about auth and key lifecycle, the token bill that has no REST analogue, how error text stops being a debugging afterthought, and a decision ladder you can run down in five minutes. If the protocol itself is new to you, the primer What Is MCP? Model Context Protocol Explained goes through the primitives one at a time.

Two Contracts, Two Readers

Think of a REST API as a parts catalogue. Every part has a number, a diagram, and a tolerance. It is exhaustive, precise, and completely silent on which part you need. That silence is fine, because a human engineer read the catalogue last quarter and wrote createJob() into the codebase. Discovery already happened, offline, once.

An MCP server is closer to the person behind the counter. You describe the problem in your own words; they tell you what is in stock, what each thing is for, and what to do when the obvious answer is out. The catalogue still exists behind them — but the interface you touch is a short list of capabilities plus an explanation of when each applies.

Every difference below falls out of that one change of reader. A human reader has a browser, a search box, and unlimited patience for a 400-page reference. A model reader has a context window measured in tokens, no ability to open a second tab mid-call, and a strong tendency to act on whatever text you actually put in front of it. Documentation stops being a website and becomes part of the runtime payload. Once you accept that, the design consequences stop looking arbitrary.

One consequence deserves stating early because it surprises backend teams: on an MCP server, the description field is not documentation about the interface. It is the interface. A tool whose behaviour is perfect and whose description is vague will simply never be called.

The Handshake REST Never Had

MCP is an open protocol introduced by Anthropic in late 2024 for connecting LLM applications to external capabilities. It runs on JSON-RPC 2.0. A session opens with an initialize exchange in which client and server agree on a protocol version and declare capabilities; only after that can the client enumerate and invoke what the server offers.

Three server-side primitives are defined. Tools are model-invoked actions carrying JSON Schema for their inputs — the nearest relative of a REST endpoint. Resources are addressable read-only context the host application can attach to a conversation. Prompts are reusable templates a user invokes deliberately. In practice most integrations are tools and little else.

Two transports matter. stdio launches the server as a local subprocess and speaks JSON-RPC over standard input and output, which suits filesystem and developer-machine work. Streamable HTTP puts the server at a single remote URL, with server-sent events available when a response needs to stream. Latency, credential custody, and who carries the deployment burden all differ between them; Remote MCP vs Local MCP Servers is the page that works through that trade.

The step with no REST counterpart is tools/list. The client asks the server what it can do and receives names, one-or-two-sentence descriptions, and an input schema for each tool. That response goes into the model's context. It is why an MCP server can be added to a client that has never heard of your product and be useful in the same session, with no code generation, no SDK release, and no version bump on the client side.

Tracing a Livestream Job Through Both Interfaces

Abstract comparisons hide the interesting part, so take a task with real shape to it: watch a livestream, cut the good moments while it runs, extend the watch if it goes long, and stop cleanly at the end. That workflow is stateful, open-ended in duration, and requires a judgement call partway through — a decent stress test for both interfaces.

Written against an HTTP API, your process owns the entire loop:

your code ──POST /sessions {stream_url}────────▶ 202 {"id":"s_44"}
     │
     │  you wrote all of this: interval, backoff, jitter,
     │  max wall clock, cancellation, crash recovery
     ▼
your code ──GET  /sessions/s_44 ───────────────▶ 200 {"state":"live"}
your code ──GET  /sessions/s_44 ───────────────▶ 200 {"state":"live"}
your code ──PATCH /sessions/s_44 {ttl:+3600} ──▶ 200   ← your rule fired
your code ──GET  /sessions/s_44 ───────────────▶ 200 {"state":"ended"}
     │
     ▼
parse against a type you declared at build time

Note where the intelligence sits. The decision to extend came from a threshold you hard-coded — probably something like "if the stream is still live at 90% of the window, add an hour." That rule was written before anyone knew what the stream would be.

The same task over MCP moves the loop, and the judgement, to the model:

user: "watch this stream and grab the best bits, I'm going out"
     │
     ▼
  MCP client (Claude Code, Claude Desktop, Windsurf, …)
     │
     │ 1. initialize    → version + capability negotiation
     │ 2. tools/list    → names, descriptions, input schemas
     │                    for every tool, loaded into context
     ├────────────────────────────────▶ MCP server ──▶ internal services
     │ 3. tools/call {name, arguments}
     ◀────────────────────────────────┤
     │ 4. content blocks appended to the conversation
     ▼
  model reads the result and picks the next move:
  poll again, extend, stop, ask the user, or answer

Step 2 is the load-bearing one. Step 4 is the subtle one: the tool's output text is what the model reasons over, so a response that says "still monitoring, no new clips in the last four minutes" produces different behaviour from one that says {"state":"live"}. The architecture underneath — routing, session handling, how a call becomes work — is unpacked in How MCP Servers Work: Architecture and Request Flow.

Side by Side on the Dimensions That Change Your Design

The comparison below assumes a streamable-HTTP MCP server, since that is the deployment most comparable to a hosted API. A stdio server differs mainly in credential handling and where the process runs.

Two rows are worth pausing on. "Adding a capability" is the strongest operational argument for an MCP surface: shipping a tool reaches every connected client immediately, with no coordinated release. "Testing surface" is the strongest argument against underestimating one: contract tests will pass on a server whose two tools have descriptions a model cannot tell apart.

What the Wire Actually Looks Like

A conventional API call is one line of curl and the failure is a status code:

curl -sS https://api.example.com/v1/sessions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stream_url":"https://twitch.tv/…"}'

An MCP call is a JSON-RPC message. The method name travels in the body, never in the path, and every request goes to the same URL:

{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"list_templates","arguments":{}}}

Do not expect to fire either of those at a live server with curl and get a clean result. A spec-compliant streamable-HTTP server will typically reject tools/list that arrives before an initialize handshake, and it may issue a session id in a response header that the client is required to echo on every later request. A non-2xx from a hand-rolled call is the normal outcome, not evidence that the endpoint is down or your credential is wrong. Treat the snippets above as an illustration of message shape and let a client library own the handshake.

The official SDKs handle initialization, session ids, and stream parsing. Here is a Node client that connects, prints everything the server advertises, and then calls one tool — the programmatic equivalent of reading the docs and trying an example:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport }
  from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://api.clipspeed.ai/mcp"),
  {
    requestInit: {
      headers: { Authorization: `Bearer ${process.env.CLIPSPEED_API_KEY}` }
    }
  }
);

const client = new Client({ name: "capability-probe", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
for (const t of tools) {
  console.log(t.name);
  console.log("  ", t.description);
  console.log("  ", JSON.stringify(t.inputSchema));
}

const styles = await client.callTool({
  name: "list_templates",
  arguments: {}
});
console.log(styles.content);

await client.close();

Python is the same three moves — open a transport, start a session, initialize:

import asyncio, os
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

URL = "https://api.clipspeed.ai/mcp"
HEADERS = {"Authorization": f"Bearer {os.environ['CLIPSPEED_API_KEY']}"}

async def main():
    async with streamablehttp_client(URL, headers=HEADERS) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            listing = await session.list_tools()
            for tool in listing.tools:
                print(tool.name, "—", tool.description)
            print(await session.call_tool("list_templates", {}))

asyncio.run(main())

Point either at a different compliant server and it still works. That portability is the practical dividend of a standard: one client implementation, many servers, no per-vendor SDK.

Installing Instead of Integrating

Most people never write that client. They add the server to an application they already use and then talk to it. For a CLI client the whole integration is one command:

claude mcp add --transport http clipspeed https://api.clipspeed.ai/mcp \
  --header "Authorization: Bearer <API_KEY>"

That is the canonical install line for ClipSpeedAI, and it is the only configuration worth copying verbatim from a general comparison page. Other applications differ in where their MCP configuration lives and what the keys are called, and those shapes change as clients evolve. The portable instruction is the one that survives: add ClipSpeedAI as an HTTP MCP server pointed at https://api.clipspeed.ai/mcp, with your key in an Authorization: Bearer header, following that client's own MCP documentation. An npm package also exists for people who prefer installing from a registry.

Support is not uniform, and it is worth being precise about it. Claude on claude.ai, Claude Code, Claude Desktop, and Windsurf are verified end to end. Cursor, Codex, OpenClaw, and Hermes speak the same protocol and work on that basis, with end-to-end verification still in progress. ChatGPT support is vendor-gated and unverified. Where behaviour diverges, the cause is almost always the client's own MCP implementation rather than anything server-side — Claude Code vs Cursor for MCP Workflows gets into where that shows up during daily work.

For step-by-step setup, ClipSpeedAI MCP for Claude Code: Complete Setup Guide takes the terminal path. Desktop users should start from ClipSpeedAI MCP for Claude Desktop: Complete Setup Guide. Editor users have ClipSpeedAI MCP for Windsurf: Complete Setup Guide, and there is a parallel walkthrough in ClipSpeedAI MCP for Cursor: Complete Setup Guide.

Nothing equivalent exists on the REST side. You cannot hand a chat application a base URL and a key and have it usefully call an arbitrary API, because nothing in that contract tells the model what the endpoints mean or when invoking one is appropriate.

Credentials: Where the Two Models Diverge Hardest

With an API you pick the auth scheme and every client adapts to it. With MCP the client class effectively picks, and your server accommodates both.

OAuth is what GUI clients want. The user clicks connect, authorises in a browser, and the application holds a token it can refresh. No secret is ever pasted into a text field, and nothing sensitive lands in a config file that gets committed by accident. MCP's authorization work builds on OAuth 2.1 and includes discovery so a client can locate the authorization server without hard-coded settings.

Bearer keys are what CLI and headless contexts want. One header, no browser round trip, works in CI. The cost is the standard cost of long-lived secrets: they end up in shell history, dotfiles, and screenshots.

Which is why key lifecycle matters more than key format, and it is worth seeing a concrete implementation rather than a principle. ClipSpeedAI keys are issued as csai_live_ followed by 48 hexadecimal characters, generated from 24 random bytes. You create one with POST /auth/api-keys, or through the interface under Account → API & Integrations → Generate API Key. Only the prefix is retained for display — the first 18 characters, then an ellipsis — so the full value appears exactly once, at creation, and cannot be recovered afterwards. Losing it means issuing a new one.

GET /auth/api-keys lists what exists, with per-key detail that is genuinely useful for operations: name, key prefix, plan, rate limit, requests today, total requests, last request timestamp, active flag, and creation date. Because the rate limit and counters are attached to the key rather than the account, one key per machine or per agent gives you both isolation and per-caller visibility — you can see which integration is generating load without instrumenting anything.

DELETE /auth/api-keys/:id revokes a key: it sets is_active to false and stamps a revocation timestamp. Revocation being real, per-key, and immediate is what makes the one-key-per-machine discipline worth following. A laptop is lost, you kill that key, and every other integration keeps running.

The working rule: OAuth whenever a human is looking at a UI, a scoped and separately revocable key whenever a process runs unattended. MCP Authentication: OAuth and Bearer Keys is the deeper treatment of both flows.

Ten Tools, Read as a Design Study

The most useful way to learn tool design is to read a real tool set and ask why each name and default is what it is. ClipSpeedAI exposes a streamable-HTTP MCP server at https://api.clipspeed.ai/mcp with ten tools, grouped here by the job they belong to rather than alphabetically:

Four design decisions are visible in that table, and each generalises.

Names describe intentions, not resources. check_clips tells a model what it will get. A path like GET /v1/projects/{id}/artifacts tells it almost nothing without prose the model never sees. Consolidation follows the same logic: creator_pack is one call for titles, hooks, and timing, where a resource-oriented design would naturally split those into three.

Lifecycle verbs beat generic mutation. The four live tools are start, check, extend, stop. An agent watching a stream that runs long needs an obvious "give it more time" action; a general-purpose update call with a TTL field conveys far less to a reader holding only a name and a sentence. Livestream Clipping API: Clip While You Stream follows that workflow through from first clip to teardown.

Enumerations belong in a tool, not only in a schema. Caption styles could have been a free-text field with the valid values buried in a schema description. Making list_templates a callable tool means a model that has never seen this server can retrieve karaoke, hormozi, beasty, fire, youshaei, and cinematic at runtime and pass a real id, instead of inventing a plausible one like "bold" and getting a validation error.

Destructive defaults point inward. publish_to_youtube defaults to private. The caller is probabilistic, so the safe outcome has to be the one that happens when nobody specified. That principle is where an outward-facing action deserves confirmation semantics, and it is the practical heart of MCP Security: Scopes, Keys and Safe Tool Design.

The inverse of these decisions is what makes machine-generated tool sets disappointing. Point a generator at a forty-operation specification and you get forty tools whose descriptions are all restatements of their own names. Nothing is wrong with any single one; the problem is that they stop being distinguishable from each other, which is precisely the signal a model uses to choose. Start from the three to six outcomes people actually ask for, name those, and let the rest stay internal. MCP Tool Design: Writing Tools an Agent Can Actually Use is the full treatment of that consolidation work.

One account note, since it comes up when teams evaluate: access is paid. A one-time $1 charge opens a three-day trial that converts unless cancelled, and plans run Starter at $15 a month, Pro at $29, and Ultra at $49, with annual billing saving 50%. There is no free tier, though a free demo covers a single video under 30 minutes.

Workloads Where MCP Is the Wrong Tool

Comparison pages tend to skip this part. MCP is a poor choice for several ordinary workloads, and choosing it anyway produces systems that are slower and more expensive than what they replaced.

• High-volume batch work. Pushing ten thousand records through a model that reasons about each call costs far more than a loop over an endpoint. If the sequence is knowable in advance, having a model decide it adds latency and expense for nothing.
• Tight latency budgets. Every tool call round-trips through inference. If your p99 target is tens of milliseconds, this is not the interface.
• Auditable determinism. A model may call a tool twice, skip one, or supply a plausible-but-wrong argument. Where the exact call sequence is itself a compliance artefact, deterministic code is the correct control.
• Very large payloads. Tool results land in a context window. A multi-megabyte response is not merely wasteful, it will be truncated. Conventional clients stream and page; a model cannot.
• Fine-grained CRUD. Resource hierarchies want to be complete; tool sets want to be small and semantically distinct. Those goals pull against each other, and completeness loses.
• Public cacheable reads. If a CDN can serve it, let a CDN serve it. There is no caching layer in front of a tool call.

Workloads Where REST Runs Out of Road

The reverse case is narrower, and each item is a genuine structural limit rather than a preference.

• The call sequence is unknown until runtime. "Find something worth clipping in this niche, cut it, and tell me whether any of it is good enough to post" cannot be written as a fixed pipeline. Step two depends on the content of step one, and step three is a judgement about quality.
• The request arrives as natural language. Turning arbitrary phrasing into the right call with the right arguments is work a model does well and a hand-written router does badly, and the router needs updating every time a user phrases something new.
• Integration cost does not amortise. Every additional client is another integration, and the work does not get cheaper with repetition. One compliant server reaches every compliant client, which is why a single endpoint serves Claude, Claude Code, Claude Desktop, and Windsurf without per-client server builds.
• The operator is not a developer. Someone who will never write a client can still direct tools through a conversation. MCP for Creators: Automating Video Without Code is written for exactly that reader.

There is a fifth case that is really a business observation: capability discovery is distribution. A tool that appears in tools/list can be found and used by someone who never visited your documentation. No API has that property.

The Token Bill Nobody Budgets For

API cost is bandwidth plus compute. MCP cost is bandwidth plus compute plus tokens, and the token term is frequently the one that dominates.

The cost has two halves and both are easy to miss. The advertised tool set occupies context in every request of a session, because the model must see the list to choose from it. A server offering dozens of tools with paragraph-long descriptions spends a meaningful slice of the window before the user has typed a character. The results are worse, because they accumulate: every tool response is appended to the conversation and stays there. A polling tool that returns full job JSON on each check can exhaust a context window quickly, and the failure is not a clean error — it is a model that has quietly lost the earlier part of the conversation.

Four mitigations, in the order they pay off:

• Keep the advertised set small and the descriptions dense. Every tool you add makes every other tool slightly harder to select correctly.
• Return a summary plus an identifier, not the full payload. Let a second call fetch detail when the model actually needs it.
• Truncate deliberately and say that you truncated. Silent tail-cutting by the client is worse than an explicit note that more exists.
• Rate-limit per credential and state the wait in prose, because the model is the thing deciding when to try again.

Latency compounds differently too. Five HTTP calls cost five round trips. Five tool calls cost five round trips plus five inference steps. That is entirely acceptable for a task a person is waiting on conversationally, and unacceptable inside a request handler rendering a page.

Error Text Is Part of the Interface

In a conventional API an error is a status code and a body; your catch block decides what happens next and the text can be terse because a human will read the logs eventually.

MCP has two distinct failure classes, and conflating them causes real bugs. A protocol error — malformed request, unknown method, transport failure — is a JSON-RPC error and generally means the session is broken. A tool execution error is a successful JSON-RPC response carrying an isError flag and explanatory content. The second kind is designed to reach the model so the model can adapt, which means its wording is a design decision, not a debugging afterthought.

HTTP:  429 Too Many Requests
       {"error":"rate_limited","retry_after":30}

Tool:  isError: true
       "Rate limit reached on this key. Wait about 30 seconds
        before calling this tool again. Do not submit the same
        video a second time — the earlier job is queued and
        will finish on its own."

The second version can prevent a duplicate submission. The first gives a model nothing to reason about beyond a number and a code, so resubmitting looks like a reasonable next move. The same logic applies to every state a caller might misread: check_livestream returning "monitoring" is a good example of a status that explains itself, where a bare enum value would invite a model to decide the session had stalled.

Retries are the other asymmetry. Conventional clients retry on a schedule you control. Models retry on judgement, sometimes more and sometimes less than you would like. Make write tools idempotent where the domain allows it, and say so in the description — that sentence is the only place the model will learn it.

Objections We Get From Backend Teams

These come up in roughly this order whenever an API-first team evaluates adding a tool surface.

"This is our API with extra steps and a slower caller." The extra step is runtime discovery, and it is the entire point. Nothing in an HTTP contract tells a caller which endpoint fits an unfamiliar request; tools/list does, in-band, at connect time, to a client that had no prior knowledge of you.

"It's really just function calling with a spec bolted on." Function calling is a model-API feature: you describe functions inside a single request and the model returns a structured call for your code to execute. There is no transport, no discovery handshake, no session, and no portable server that a different vendor's client can connect to. MCP vs Function Calling: What Actually Differs untangles the two, and that confusion is the most common one in this area.

"This locks us to one vendor." The specification is open and implemented across multiple clients, and a server has no idea which model sits on the other end of the session. The clients differ; the server does not need to.

"So we'd be building and operating one of these per client." No. One compliant HTTP server serves every compliant client. Where support varies, the variance lives in client implementations, which is a very different maintenance burden from N server builds.

"Servers have to run on the user's machine, and we're not shipping a binary." Only stdio servers do. A streamable-HTTP server is an ordinary hosted service behind your existing infrastructure, deployed the way you deploy everything else.

"It's inherently less secure." It is differently exposed. The transport is not the novel risk; prompt-injected tool invocation and over-broad scopes are. Per-key credentials with real revocation, safe defaults on outward-facing actions, and confirmation on anything that spends money or publishes cover most of the surface.

"If it works in Claude Code it works everywhere." Protocol compliance varies between clients, so verify against the tier your users are actually on rather than assuming parity.

A Decision Ladder

Work down this list and stop at the first clear answer. Most teams settle it within three rungs.

1. Is the sequence of calls knowable before the program runs? Yes, use an API. No, you need discovery.
2. Does the workload run thousands of times per hour? Yes, use an API regardless of anything below.
3. Is a human phrasing the request in a chat interface? Yes, MCP.
4. Must the result be identical on every run, and provably so? Yes, deterministic code.
5. Do you need to reach many different LLM applications? Yes, one MCP server rather than one integration per client.
6. Are payloads large or streaming? Move the data over HTTP and use MCP only for the control plane.
7. Is the operator a non-developer? Yes, MCP.
8. Do you already have a working HTTP service and want agents on it? Add a tool surface in front; do not migrate anything.

Most mature products end up answering "both," split by caller rather than by feature: HTTP for the product's own frontend, partner integrations, and scheduled work; MCP for interactive and agentic use. AI Agent Video Automation: End-to-End Workflows shows that split running in a single domain. For the editing-specific version of the same split, there is MCP for Video Editing and Clipping Workflows. If your evaluation is currently on the developer-integration side, Video Clipping API for Developers is the companion read.

Shipping an MCP Surface Beside an API You Already Have

A pragmatic order of operations, and the order matters more than it looks:

1. List outcomes, not endpoints. "Turn this stream into clips while it runs" is an outcome. "List session artefacts" is an endpoint. Pick three to six outcomes.
2. Write the descriptions before the code. If you cannot say in two sentences when a tool should be used and when it should not, a model will not infer it, and no amount of implementation quality compensates.
3. Wrap, do not rebuild. Handlers should call the services you already run, using a service credential or the user's own token. Your rate limits, metrics, and audit logging keep working unchanged, which is also what keeps the adapter thin enough to stay maintained.
4. Shape responses for reading. Short text or small structured blocks, with the identifier needed to fetch more. Assume every byte you return is paid for twice — once on the wire and once in the window.
5. Decide the credential story per client class, following the OAuth-versus-key split described earlier, and make keys individually revocable before you publish anything.
6. Gate outward-facing actions. Publishing, deleting, and spending need confirmation semantics and safe defaults, because the caller is probabilistic by construction.
7. Test with a real model, not with curl. curl proves the server responds. Only a transcript reveals that two of your tools have descriptions the model cannot tell apart, or that your error text talked it into a duplicate submission.

The failure mode to watch is tool-list creep. Ship fewer tools than you think you need and add one only when a real transcript shows the gap. If you are writing the server rather than consuming one, How to Build an MCP Server (Practical Guide) is the implementation-side companion to this page.

If You Only Keep Three Things

First: the deciding question is who holds the contract at call time. Code that already knows what it wants is best served by an HTTP API. A model deciding what to want needs discovery, and discovery is the one thing REST structurally cannot provide.

Second: the pairing is not a compromise, it is the normal outcome. Keep your existing service as the system of record and the high-volume path, and add a small, deliberately designed tool surface for agents and for people working conversationally. Thin adapter, few tools, descriptions and error strings written as though a model will read them — because one will.

Third: budget tokens the way you budget latency. The advertised tool set and every result you return are charged against a finite window, and the cost of a chatty tool shows up as degraded reasoning rather than as an error you can alert on.

If you are choosing a server to connect rather than building one, Best MCP Servers for Video and Content Workflows surveys what is available in this domain and what each one is actually good at.

Frequently asked questions

Is MCP a replacement for REST APIs?

No, and treating it as one usually breaks something. The two serve different callers: deterministic code on one side, a model choosing actions at runtime on the other. A common production shape is a small MCP server translating for agents while the existing HTTP service keeps serving the frontend, partner integrations, and scheduled work. Removing the HTTP layer would strand every non-agent consumer, and it would also throw away the rate limiting, metrics, and audit logging you have already built around it.

What is the single clearest signal that I need MCP rather than an API?

Whether the sequence of calls is knowable before the program runs. If your code can decide the calls in advance, plain HTTP is simpler, faster, cheaper, and deterministic. If the next call depends on interpreting the previous result, or on a request phrased in natural language, the caller needs to discover capabilities at connect time. That is what the tools/list handshake provides and what an OpenAPI document, sitting on a docs site the runtime never visits, cannot.

Can I generate an MCP server from my OpenAPI spec and be finished?

You can generate one, but plan on rewriting the tool layer. Generation emits one tool per operation, so the descriptions end up as restatements of the operation names and stop being distinguishable from one another, which is the signal a model uses to choose. The productive path is to treat the generated server as a private backend and hand-write a small set of outcome-shaped tools in front of it. Start from the three to six things users actually ask for, fold list-filter-sort-paginate variants into single tools with optional arguments, and add more only when a transcript shows a real gap.

How should I manage API keys for an MCP integration?

Issue one key per machine or per agent rather than one per account, so load is attributable and revocation is surgical. ClipSpeedAI keys look like csai_live_ followed by 48 hexadecimal characters and are created with POST /auth/api-keys, or through Account then API & Integrations then Generate API Key. Only the first 18 characters are stored for display, so the full value is shown once at creation and cannot be retrieved later. GET /auth/api-keys lists each key with its plan, rate limit, requests today, total requests, and last request time; DELETE /auth/api-keys/:id revokes it, setting is_active to false and stamping a revocation timestamp.

Why do MCP tool results need to be smaller than API responses?

Because they are cumulative. A tool result is appended to the conversation and stays there for the remainder of the session, so a chatty polling tool spends window on every check and never gets it back. A conventional client can stream or page through a large payload and discard what it has processed; a model cannot. Return a summary plus an identifier and let a second tool fetch detail on demand. The advertised tool descriptions cost context in every request too, which is a second reason to keep the tool set small.

Does supporting many AI clients mean building many MCP servers?

No. One compliant streamable-HTTP server serves every compliant client, and ClipSpeedAI runs exactly one endpoint at https://api.clipspeed.ai/mcp for all of them, with OAuth for GUI clients and a bearer header for CLI clients. Claude, Claude Code, Claude Desktop, and Windsurf are verified end to end. Cursor, Codex, OpenClaw, and Hermes speak the same protocol with verification still in progress, and ChatGPT support is vendor-gated and unverified. Where behaviour differs, the cause is the client's own MCP implementation, not a separate server build.

How should errors be written differently in an MCP server?

Separate the two classes first. A protocol error is a JSON-RPC error and usually means the session is broken. A tool execution error is a successful response carrying an isError flag and explanatory content, and that one is read by the model. Write it as instructions rather than a code: say how long to wait, say what state the previous work is in, and say explicitly not to resubmit if a job is already queued. A bare 429 with a retry_after integer gives a model nothing to reason about, so resubmitting can look like a sensible next move.

How do I test an MCP server, given the caller is non-deterministic?

Keep your existing contract tests for the handlers, then add a second layer that curl cannot reach. Connect a real model and read transcripts, looking for three specific failures: the model picking the wrong tool because two descriptions overlap, the model inventing an argument value instead of calling the tool that enumerates valid ones, and the model retrying after an error message that did not tell it what state the work was in. All three pass a schema check and all three are description problems, not code problems.

When is MCP simply the wrong choice?

High-volume batch processing, latency budgets measured in milliseconds, workloads where the exact call sequence is a compliance artefact, payloads large enough to be truncated in a context window, and fine-grained CRUD surfaces that would produce dozens of confusable tools. In each of those, ordinary code calling an ordinary endpoint is faster, cheaper, and more predictable. Public cacheable reads belong on a CDN for the same reason: there is no caching layer in front of a tool call.

Related reading