REST API vs MCP server comes down to one question: who is calling CoreReflex, code or an AI agent? The REST API is direct HTTP for pipelines, backends, and schedulers that know exactly what they want. The MCP server exposes the same capabilities as discoverable tools an LLM agent can reason about and invoke on its own. Both drive the same underlying engine, so the choice is about the caller, not the feature set.
What the REST API is
The REST API is the conventional way to drive CoreReflex programmatically. You authenticate with an API key, send HTTP requests to documented endpoints, and get structured JSON back. It is explicit and predictable: you decide which call to make, with which parameters, in which order. That makes it the natural fit for any system where the steps are known ahead of time, a backend service, a cron job, a build pipeline, a queue worker.
Underneath, the API is a thin, stable surface over the platform's programmable JSON engine, which is the same engine that represents editor state. So a script can plan a film, kick off generation, poll for completion, and assemble a cut without ever opening the editor. If you want a concrete starting point, our API quickstart for developers walks through your first authenticated calls, and the AI video API shows how to turn one sentence into a film over HTTP.
What the MCP server is
MCP, the Model Context Protocol, is an open standard for exposing tools and data to AI models in a way they can discover and call. CoreReflex ships an MCP server that presents its capabilities as MCP tools. Connect an MCP-aware assistant, and the agent can list the available tools, read their schemas, and decide which to invoke to satisfy a request phrased in plain language, "board a 15-second product teaser and generate the first three shots."
The distinction that matters: with the REST API, your code chooses the calls. With MCP, the model chooses the calls, guided by tool descriptions and the user's intent. The MCP server is the same set of capabilities, repackaged so an autonomous agent can use them without you hand-coding every branch. Both sit on top of the same JSON engine, which is why a workflow built one way can usually be expressed the other.
Head to head: REST API vs MCP
| Criterion | REST API | MCP server |
|---|---|---|
| Primary caller | Your code | An AI agent / LLM |
| Who chooses the steps | You, explicitly | The model, from tool schemas |
| Best for | Pipelines, backends, schedulers | Assistants, agentic workflows |
| Determinism | High, fixed calls, fixed order | Depends on the model's reasoning |
| Discovery | Read the docs | Agent reads tool schemas at runtime |
| Auth | API keys | MCP client connection |
| Long-running jobs | You poll or use webhooks | Agent invokes and follows up |
The table makes the split clear. The REST API trades flexibility for control and repeatability; the MCP server trades some determinism for the ability to handle open-ended, natural-language requests without you anticipating every path.
When to use the REST API
Reach for the REST API when the workflow is known and you want it to run the same way every time.
- Scheduled generation. A nightly job that produces a batch of social cuts does not need a model deciding what to do. It needs the same calls on a timer. Pair it with the batch API to generate at scale.
- Backend integration. Embedding CoreReflex inside your own app, where your server orchestrates the calls and owns the UX.
- Deterministic pipelines. CI-style flows where you want identical behavior on every run and clear, inspectable failures.
- Tight cost control. When you want to call exactly the endpoints you intend and nothing more. Layering in the context cache to cut latency and token cost keeps repeated calls cheap.
If your system already knows what it wants, the directness of HTTP is a feature, not a limitation.
When to use the MCP server
Reach for the MCP server when an AI agent is the one doing the work.
- Assistant-driven creation. A user talks to an assistant in natural language, and the agent translates intent into the right sequence of CoreReflex tool calls.
- Agentic workflows. A multi-step agent that plans, generates, inspects results, and adapts, invoking tools as it reasons rather than following a fixed script.
- Dynamic tool use. Cases where the next step depends on the last result, and hard-coding every branch would be brittle.
- Grounded generation. An agent that pulls from a knowledge base before it generates benefits from MCP's tool model; see the knowledge base API for grounding every generation.
The MCP server shines exactly where the REST API feels rigid: open-ended requests whose steps cannot be fully known in advance.
Using both together
This is not an either-or decision, and most serious setups use both. A common pattern: an MCP-driven assistant handles the exploratory, conversational front end, shaping the brief, boarding shots, iterating on a look, while a REST-based backend handles the deterministic, high-volume back end, like scheduled re-renders and batch exports. The assistant figures out what to make; the pipeline reliably makes it at scale.
Because both interfaces sit over the same JSON engine and the same render path, work flows between them cleanly. An agent can produce a plan over MCP that your backend later renders over REST and scores with the eval API, with the same provenance trace attached throughout.
Honest verdict
If you are writing code that knows what it wants, start with the REST API, it is more direct, more predictable, and easier to reason about when something breaks. If you are building or connecting an AI agent that should decide what to do from natural-language intent, use the MCP server so the model can discover and call tools itself. And if you are doing both, a smart conversational layer over a dependable execution layer, run them together. The capabilities are identical; you are choosing the interface that matches the caller.
Frequently asked questions
Should I use the REST API or the MCP server?
Use the REST API when your own code orchestrates the steps and you want deterministic, repeatable behavior, backends, schedulers, batch jobs. Use the MCP server when an AI agent should choose the steps from natural-language intent. The deciding factor is whether code or a model is making the decisions.
Can I use both the API and MCP together?
Yes, and it is a common pattern. An MCP-driven assistant handles open-ended, conversational creation while a REST-based backend handles deterministic, high-volume execution. Both sit over the same JSON engine and render path, so plans and assets move between them without translation.
Do the REST API and MCP server expose the same capabilities?
Largely, yes, both are surfaces over the same programmable JSON engine, so the core platform capabilities are reachable either way. The difference is packaging: REST presents fixed endpoints you call explicitly, while MCP presents tools with schemas an agent discovers and invokes at runtime.
How do I authenticate each one?
The REST API uses API keys you generate and send with each request. The MCP server is reached through an MCP client connection from an MCP-aware assistant. The documentation covers the exact setup for both.
Pick the interface, ship the work
The REST API and the MCP server are two doors into the same studio, one for code that knows the plan, one for agents that work it out as they go. Choose by who is calling, or use both and let each do what it is best at. For more developer guides, browse the developers category, then start free with no credit card and generate your first API key.