API or MCP — Which Should I Use?
Use the REST API when your own code drives the pipeline; use the MCP
server when you want an AI agent to drive it. Both reach the exact same
pipeline over the same authenticated surface with the same hfk_… key — the
choice is about who calls the endpoints, not about what they can do.
Should I use the InvesTeam API or the MCP server?¶
Choose the API if you are integrating from a backend you control — a service, a job, a web app — and you want direct HTTP requests and responses. Choose MCP if you are building on an AI client (like Claude) and you want the model to decide when to create a brief, answer clarifications, and read findings as it works.
A quick way to decide:
- You write the control flow → REST API. You send
POST /api/v1/briefs, read thesession_id, and poll on your schedule. - The agent writes the control flow → MCP. The model calls
create_brief, thenget_brief, and reasons about the results between calls.
Nothing stops you from using both — an application backend on the API, an in-product assistant on MCP — against the same keys and sessions.
What's the difference between the InvesTeam API and MCP?¶
The difference is the integration shape, not the capability. The REST API is a set of HTTP endpoints; the MCP server is a thin, faithful projection of those same endpoints as callable tools. The MCP server is itself only a client of the public API — it performs no orchestration of its own, holds no privileged access, and cannot reach anything the API cannot.
| REST API | MCP server | |
|---|---|---|
| Who calls it | Your code | An AI agent / client |
| Surface | HTTP endpoints under /api/v1 |
Tools (create_brief, get_brief, …) |
| Auth | Authorization: Bearer hfk_… |
The same hfk_… key, forwarded to the API |
| Control flow | You write it | The agent reasons through it |
| Underlying pipeline | The same submit → poll pipeline | The same submit → poll pipeline |
Because the MCP tools are generated from the same public API spec, the two surfaces cannot drift: a tool always maps to a real endpoint. See the MCP Tool Catalog for the 1:1 mapping.
Which one is faster to get working?¶
MCP is usually faster to a first result because the setup is a config paste
rather than code — the MCP Quickstart targets under ten
minutes. The API Quickstart targets under fifteen. Both
end at the same "you did it" moment: a real session_id in hand.
Where should I go next?¶
If you picked the API, continue to Authentication & API Keys and then the async submit → poll model. If you picked MCP, start at What Is MCP and Connect to Claude. Either way, Capabilities & Limits sets the boundary of what the pipeline does.