---
title: Choose MCP, REST, or S3
category: connect
summary: Pick the right Synorb access point for an interactive agent, a scheduled job, or a bulk history load, then make a first call that works.
order: 1
updated: 2026-10-07
next: get-a-key-with-connect
related: quotas-retries-and-pagination, schedule-six-hour-and-daily-pulls
reference: /docs/mcp, /docs/api, /agent-guide.md
---

Synorb has one credential, the **Synorb Key**, and several ways to reach the same Streams and the same source-cited Manifests. The access point you choose does not change what data you can see. It changes latency, who holds state, and how failures reach your code.

## When to use this

Read this before you write any integration code. It decides which of the next guides you need.

| Your situation | Use | Why |
| --- | --- | --- |
| A chat or copilot agent that answers while your user waits | **MCP Core**: `https://mcp.synorb.com/mcp` | Tools are discoverable, and one warm Streamable HTTP session serves the whole conversation. |
| A scheduled poll, a backend job, or a product feature | **REST**: `https://api.synorb.com` | Stateless and deterministic. Every call carries its own deadline (`timeout_ms`). |
| An agent that needs tools beyond the ten Core tools | **MCP Advanced**: `https://mcp.synorb.com/advanced/mcp` | Same key, wider tool set. |
| A voice agent | **MCP Core**, narrow scopes | Latency is the constraint. One Manifest pull is a complete answer. |
| A one-time bulk or historical load | **S3 export** (Startup and Enterprise plans) | Built for bulk delivery, not for polling. |

Do not use the legacy `/sse` MCP transport for new work. It is deprecated, with sunset on 2026-11-01. Do not call Synorb from browser code, because the key would be exposed.

A Beacon (a saved watch) works over both MCP and REST. Whichever you choose, **your runtime does the scheduling**. Synorb never runs a Beacon on a clock and never pushes one at you. The scheduling guide covers this.

## Smallest working call

Start with a call that needs no key at all. The health probe is safe for discovery and readiness checks.

```bash
curl -sS https://api.synorb.com/health
```

With a key in `$SYNORB_KEY` (the next guide shows how to get one in a minute), ask the account who you are. This call is free: it never bills Manifest usage.

```bash
curl -sS https://api.synorb.com/account \
  -H "Authorization: Bearer $SYNORB_KEY"
```

The MCP equivalent is the `synorb-profile` tool. It takes no required arguments.

```mcp
synorb-profile
{"verbosity": "minimal"}
```

MCP connection facts, for whatever client you use:

- URL: `https://mcp.synorb.com/mcp` (Core) or `https://mcp.synorb.com/advanced/mcp` (Advanced).
- Transport: Streamable HTTP.
- Header: `Authorization: Bearer YOUR_SYNORB_KEY`. There is no separate MCP token.

## What you get back

`GET /account` returns the usual envelope. These are the fields to read first. The values below are illustrative.

```json response
{
  "data": {
    "usage": {"manifests_used": 3, "manifests_remaining": 22, "beacons_used": 1},
    "temporal": {
      "refresh_tier": "daily",
      "relative_anchor": "available_through",
      "available_through": "2026-10-06",
      "wall_clock_date": "2026-10-07",
      "lag_days": 1
    }
  }
}
```

`temporal.available_through` is the newest date your plan can see. Relative windows such as `days=1` anchor to it, not to the wall clock. The freshness guide explains why this matters.

`synorb-profile` returns your account, plan, usage, tool routing and freshness. Like the other agent tools, its response carries a top-level `next_call` that suggests what to do next.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| `401` with `synorb_key_invalid` or `synorb_key_expired` | Wrong, revoked or expired key | Mint a fresh key (next guide). Do not retry the same key. |
| MCP returns `401` and names `synorb-get-demo-key` | No header and no `api_key` argument | Send the Bearer header, or call `synorb-get-demo-key` for a demo key. |
| `404` | Wrong route or identifier | Check [the API docs](/docs) and [openapi.json](/openapi.json). |
| `429` | Rate limit or usage limit | Branch on `detail.error_code`. See the quotas guide. |
| An MCP call times out | MCP uses a fixed interactive budget (12 seconds by default; the deployment setting is clamped to 8 to 18 seconds) and does not accept `timeout_ms` | For a scope above roughly 200 to 250 Streams, split it into shards of about 200 and merge by `manifest_id`. |
| An MCP host cannot set headers on an open session | Some hosts cannot inject headers after connecting | Pass the key as the `api_key` argument on the tool call. This is a fallback, not the recommended path. |

REST differs from MCP on deadlines: `POST /manifests/query`, `/manifests/plan` and `/manifests/exec` accept `timeout_ms`, default 5,000 and clamped to 100 to 15,000 milliseconds.

## Make it good for your user

Tell your user which path is running. "I check Synorb when you ask" (MCP, on demand) and "a job on your server checks every six hours" (REST, scheduled) are different promises. If your runtime cannot schedule work, say plainly that no recurring run is active, and offer on-demand pulls instead of implying a schedule exists.

## Next guide

[Get a key with /connect](/agent-resources/get-a-key-with-connect): mint a working key with no email and no card, and keep it past the 72-hour demo.