MCP vs HTTP API
Mosaic exposes two surfaces over the same knowledge graph: an MCP server (for AI clients with native MCP support) and an HTTP API (for everything else). The data is the same; the wrapping isn't. This page is the short answer to "which one should I use?".
Decision in one line
If a human (or an LLM agent the human is talking to) is in the loop and you want the LLM to pick the right tool, use MCP. If a server-side script needs the graph data with no model in the loop, use the HTTP API.
Side by side
| MCP server | HTTP API | |
|---|---|---|
| Endpoint | mcp.getmosaic.dev/sse | api.getmosaic.dev/v1 |
| Transport | Server-Sent Events (SSE) | REST (JSON over HTTP) |
| Caller | Claude / Cursor / Claude Code | Any HTTP client (Python, curl, n8n, …) |
| Tool selection | Done by the LLM client | Caller picks the endpoint |
| Auth | Bearer mk_live_… via Authorization header | Same Bearer key; same scopes |
| Response shape | MCP tool_result (JSON payload + _provenance) | Same JSON payload + _provenance, returned directly |
| Streaming | Yes (SSE) | No (single response) |
| Rate limits | Per-key (see rate limits) | Per-key (same quotas) |
| When you want it | Conversational, multi-tool reasoning | Pipelines, dashboards, scheduled jobs |
The same call, both ways
Below is the same KG traversal — find_resistance_bypass_map for EGFR — invoked from each surface. The returned JSON body is byte-identical.
Via MCP (inside Claude Code)
You don't call the tool directly; you ask the model:
> Use Mosaic find_resistance_bypass_map on EGFR.
Via HTTP API
curl -X POST https://api.getmosaic.dev/v1/tools/find_resistance_bypass_map \
-H "Authorization: Bearer mk_live_xxxx" \
-H "Content-Type: application/json" \
-d '{"target": "EGFR"}'The response payload (bypass_candidates[], _provenance) is the same JSON the MCP client receives — only the outer envelope differs.
When you need both
Plenty of teams use both: MCP for exploratory work in an IDE, HTTP for nightly enrichment jobs and dashboard refresh. The same Bearer key works on both surfaces. Quotas are per-key, so a noisy script and a chat session draw from the same budget.