Connect AI agents over MCP

Which MCP server do you want?

Four things in the AllSource ecosystem speak MCP. Pick one before you copy any command — they are not interchangeable. All four speak stdio, so your client launches them as a subprocess rather than connecting to a URL. Only prime-mcp additionally exposes HTTP; the event-store connectors do not, so there is no /sse endpoint to point a client at.

The rest of this page covers allsource-mcp-server — the default. For the disk-reading Rust binary see the allsource-mcp guide; for Prime see Prime MCP.

How a secure connection is shaped

The MCP connector never talks to the database (Core) directly. Every request is mediated by the authenticated gateway at https://api.all-source.xyz, which validates your API key, scopes the call to your tenant, and enforces quotas and rate limits. Core is internal-only and trusts any caller on its network — so it is never exposed to the public, and neither your agent nor the connector should ever point at it.

Claude Desktop / Cursor
        │  (MCP — stdio, connector runs as a subprocess)
        ▼
AllSource MCP connector            ← runs on YOUR machine / your infra
        │  HTTPS + Authorization: Bearer <serviceaccount key>
        ▼
https://api.all-source.xyz  (gateway)               ← validates key, derives tenant_id
        │  internal network only
        ▼
AllSource Core (your tenant's events only)

Three properties make this safe: the key is a least-privilege, tenant-scoped credential (a scoped key can only ever read/write its own tenant's events); the transport to the gateway is TLS; and the connector runs where you control it, so your key never leaves your environment.

1. Mint a least-privilege API key

An MCP agent needs to read and write events — nothing more. Mint a key with the serviceaccount role: it is granted read + write and is denied admin, tenant management, metrics, and schema administration. Do not use an admin JWT or an admin-role key as your connector credential.

Self-service (creates a tenant and returns a scoped key in one call):

curl -X POST https://api.all-source.xyz/api/v1/onboard/start \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

# →
# {
#   "tenant_id": "my-agent-a1b2c3",
#   "api_key": "eyJhbGciOiJIUzI1NiIs...",   ← store this in a secret, shown once
#   ...
# }

Already onboarded? Mint a fresh, role-scoped key with an admin token:

curl -X POST https://api.all-source.xyz/api/v1/teams/agent-keys \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "claude-desktop", "role": "serviceaccount"}'

The role string is exactly serviceaccount — no underscore. A drifted service_account is rejected and every request silently 403s.

2. Check hosted connector release status

Do not run stable image 0.22.0 against the hosted gateway. That release does not attach CORE_API_KEY to upstream requests, so valid hosted keys still receive 401. The Authorization fix is merged for 0.23.0 but has not been published.

The connector image is an Enterprise (BSL 1.1) build, so the registry requires a login first — a GitHub token with read:packages:

gh auth token | docker login ghcr.io -u $(gh api user -q .login) --password-stdin

# LOCAL / SELF-HOSTED CORE ONLY for 0.22.0.
# stdio server: -i keeps stdin open, and there is no port to publish.
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | docker run -i --rm \
      -e CORE_URL=http://host.docker.internal:3900 \
      ghcr.io/all-source-os/allsource-mcp-server:0.22.0

# → {"jsonrpc":"2.0","id":1,"result":{...,"serverInfo":{"name":"allsource-mcp-elixir","version":"0.22.0"}}}

For hosted production today, call the gateway REST API with Authorization: Bearer $ALLSOURCE_API_KEY. Pin connector 0.23.0 only after it appears in the release registry and changelog.

3. Point your MCP client at a local connector

Stable 0.22.0 can drive local or self-hosted Core over stdio. Add this local-only configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "allsource": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "CORE_URL",
        "ghcr.io/all-source-os/allsource-mcp-server:0.22.0"
      ],
      "env": {
        "CORE_URL": "http://host.docker.internal:3900"
      }
    }
  }
}

Passing -e CORE_URL with no value forwards it from the env block rather than baking it into the argument list. Keep this Core bound to a trusted local network: direct Core has no public-tenant authentication boundary.

4. Verify the connection is tenant-scoped

Before trusting the agent, confirm the key reaches your data and only your data. The same credential against the gateway REST API:

curl "https://api.all-source.xyz/api/v1/events/query?limit=1" \
  -H "Authorization: Bearer $ALLSOURCE_API_KEY"
# → {"events": [ ... ], "count": N}   ← your tenant's events only

Connector verification against hosted data must wait for 0.23.0. A scoped REST key cannot read another tenant's events — the gateway derives the tenant from the key, not from any field the caller supplies.

Running it efficiently

Every tool the connector advertises is described in your client's context window on every turn, so the toolset is a real running cost. How many you expose depends on configuration:

• Set ALLSOURCE_READ_ONLY=true unless the agent must writeDrops the 10 mutation tools (ingest_event, delete_events, archive_events, import_events, clone_entity, merge_entities, split_entity, compact_storage, backup_create, backup_restore). Smaller context and a hard stop on accidental writes — a gated call returns a refusal rather than mutating.
• Leave ALLSOURCE_CONTROL_URL unset for a single-tenant agentThe 9 tenant and fleet-health tools only make sense for fleet operators. Unset is the default, and the tools stay hidden.
• Use the embedded image when data is localghcr.io/all-source-os/allsource-mcp-server-embedded compiles Core in-process via a Rustler NIF, removing the HTTP hop entirely. No gateway means no auth and no tenant isolation, so use it only against your own local data.
• Explore cheaply before querying broadlyquick_stats and sample_events cost far less than an unbounded query_events. get_query_advice suggests a better shape for a query, and infer_schema derives structure from existing events instead of you describing it.
• Use sessions for multi-turn workstart_session, refine_query, and get_session_context keep query state on the server, so a narrowing conversation does not re-send the full filter set every turn.
• Always bound query_eventsPass limit, and order=desc when you want the newest events. Results are ordered by (timestamp, version) ascending by default, so an unbounded query walks history from the beginning.

Staying on a current version

Pin a version rather than tracking latest, so an agent's toolset cannot change under you mid-conversation. Published tags are unprefixed semver — 0.22.0, not v0.22.0 — alongside the moving latest and main, a major.minor tag (0.22), and sha-<commit>.

Ask the connector what it is. The initialize handshake reports the build in serverInfo.version:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | docker run -i --rm ghcr.io/all-source-os/allsource-mcp-server:0.22.0 2>/dev/null \
  | grep -o '"serverInfo":{[^}]*}'
# → "serverInfo":{"name":"allsource-mcp-elixir","version":"0.22.0"}

# What is actually published:
docker run --rm gcr.io/go-containerregistry/crane ls ghcr.io/all-source-os/allsource-mcp-server

To upgrade, bump the pinned tag in your client config and restart the client — the connector is stateless, so nothing migrates. Check the changelog for tool additions or removals first; a removed tool is a breaking change for any prompt that names it.

The Docker images track platform releases. The cargo install allsource-mcp binary versions independently and currently lags the platform — check allsource-mcp --version against crates.io before relying on a recent Core feature through it.

Production hardening checklist

• Use the gateway, never CoreAlways set CORE_URL=https://api.all-source.xyz. Core is internal-only and trusts any caller on its network — pointing an external connector at it bypasses auth, quotas, and tenant isolation entirely.
• serviceaccount role, least privilegeMint the connector key as serviceaccount (read + write). Reserve admin keys for humans; never hand an admin credential to an agent.
• Read-only unless writes are requiredALLSOURCE_READ_ONLY=true is the safer default and the cheaper one. Turn it off deliberately, for a connector that genuinely ingests.
• Key in a secret, not in config (0.23.0+)After the hosted connector fix is released, inject CORE_API_KEY from an environment secret or secrets manager. Keep it out of images, compose files, claude_desktop_config.json, and git.
• TLS onlyCORE_URL must be https://. The connector → gateway hop carries your key — never run it over plain http in production.
• Pin the image tagRun a specific version, not latest, so the advertised toolset only changes when you choose. Review the changelog before bumping.
• Rotate and revokeRotate the key on a schedule and immediately if a machine running the connector is lost. Revoke from the dashboard; a revoked key fails closed.
• One key per connectorGive each connector / machine its own key so you can revoke a single one without taking down the rest, and so audit trails stay attributable.

What the agent can do

A representative slice of the toolset — all scoped to your tenant by the key:

Run tools/list against your own connector for the authoritative set — it reflects your gating, so it is the only count that matches what your agent sees.

Troubleshooting

• manifest unknown / pull failureStale image name, or not logged in. The images are allsource-mcp-server and allsource-mcp-server-embedded; the older chronos-* names no longer exist. Tags are unprefixed semver, so 0.22.0 works and v0.22.0 does not. Enterprise images also need docker login ghcr.io with a read:packages token — an unauthenticated pull reports the manifest as unknown rather than as a permission error.
• Client reports the server exited immediatelyMissing -i on docker run. This is a stdio server: without stdin held open it reads EOF and shuts down cleanly. There is no port to publish and no /sse endpoint to point a url at.
• 401 from the gatewayNo / invalid key. Confirm CORE_API_KEY is set in the connector's environment and the key hasn't been revoked or expired. Note that images up to and including 0.22.0 never sent the Authorization header at all, so a hosted Core 401s no matter what you configure — that fix lands in the next release.
• 403 on every callRole drift. The key's role must be the exact string serviceaccount (no underscore). Re-mint with the correct role.
• Fewer tools than expectedGating, not a bug. Mutation tools need ALLSOURCE_READ_ONLY unset; tenant tools need ALLSOURCE_CONTROL_URL; recovery tools additionally need ALLSOURCE_SYSTEM_ADMIN=true.
• A tool the docs mention isn't thereCheck tools/list on your connector rather than trusting a name — that list is authoritative for your version and configuration.
• Empty results but data existsWrong tenant or wrong base URL. Verify CORE_URL is the gateway and the key belongs to the tenant that owns the data — the gateway scopes by key, so a key from another tenant returns nothing, not an error.
• Connector can't reach the gatewayCheck egress/TLS from the machine running the connector to https://api.all-source.xyz. Do not work around it by pointing CORE_URL at Core.

Local development (no auth — never for production)

When you run the full AllSource stack locally, the connector points at your local Core with no key. This is convenient for development but has no authentication and no tenant isolation — only ever use it against a local Core, never against production:

# LOCAL ONLY — local Core, no auth. Do not use these values for production.
docker run -i --rm \
  -e CORE_URL=http://host.docker.internal:3900 \
  ghcr.io/all-source-os/allsource-mcp-server:0.22.0

The difference between this and a secure production connection is exactly the two things above: CORE_URL pointed at the gateway instead of a local Core, and a scoped CORE_API_KEY.

A note on hosted MCP

Today you run the MCP connector yourself (locally or on your own infrastructure) and it reaches production through the gateway — there is no public, multi-tenant hosted MCP URL to point a client at directly. If you only need to store and query events and don't want to run a connector at all, the gateway REST API and the SDKs give you the same tenant-scoped access with the same serviceaccount key.