docs
// API Reference

MCP Integration

One HTTP MCP endpoint. Nine tested clients. Twenty-five tools, six prompts, four resources, all addressable from the editor. No sidecar, no daemon, no glue.

Connect once, pin a workspace via the X-Erebine-Workspace header, and your AI tooling gains durable context about your project, the same context the chat surface already has. The header accepts either the workspace's URL-safe external identifier (ws_<hex>, the form you see in the dashboard) or the internal workspace UUID, so a value copied from a chat URL works without translation.

Supported Clients

The endpoint is a standard streamable HTTP MCP server (streamable HTTP is the default transport; a deployment can pin the legacy transport, which suppresses the streamable capability advertisement). Any client that speaks the HTTP transport will work; the following are explicitly tested and have one-shot config bundles in the Erebine dashboard:

  • Claude Code, Anthropic's CLI coding assistant.
  • Cursor, AI editor with first-class MCP support.
  • opencode, Open-source coding agent.
  • VS Code, Native MCP support (via the GitHub Copilot Chat extension).
  • Claude Desktop, HTTP MCP support is partial; works for most read tools.
  • OpenAI Codex, CLI coding agent; reads MCP servers and model providers from a TOML config.
  • Hermes Agent, Nous Research's open-source agent; reads MCP servers from a user-level YAML config.
  • pi, Earendil's minimal coding agent; no built-in MCP, the Erebine bundle ships an extension that bridges it.
  • Cline, IDE extension and CLI; native streamable-HTTP MCP from a shared global settings file.

Other HTTP-capable MCP clients work too; you may need to hand-author the configuration.

Quick Start

1. Pick a workspace on the chat page

Open /chat in the dashboard and select the workspace you want to connect from the left navigator. The Client tab in the right manager column is workspace-scoped, it only appears once a specific workspace is active (the "All" aggregate view hides it).

2. Open the Client tab

In the right manager column's tab strip, click Client. The tab surfaces a catalog tier picker and one card per supported MCP client (Claude Code, Claude Desktop, Cursor, Hermes Agent, opencode, OpenAI Codex, VS Code, pi, Cline).

3. Pick a catalog tier and download

Choose how much of the tool catalog this connection exposes (see Catalog Tiers below), then click Download next to your client. The file is a drop-in config fragment; each download rotates the workspace API key, so older bundles for the same workspace are automatically revoked.

4. Save the file at the path your client expects

Each card shows the exact path. Most clients use a project-scoped file (opencode.json, .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml, .pi/erebine.json) at your repo root; Claude Desktop, the Hermes agent and Cline merge into user-level config files instead. Add the project-scoped file to your .gitignore, the bundle carries your workspace API key in the Authorization header and should not land in version control.

  • Your client may surface prompts (as slash commands) and resources (as @-mentions). See the Prompts and Resources sections below for syntax per client.

5. (Recommended) Drop in the companion rules file

The bundle README ships a short Erebine tool-use rules snippet, the same content opencode inlines via its instructions config field and Codex via developer_instructions. For Claude Code, Cursor, and VS Code, save the snippet at the documented path (.claude/CLAUDE.md, .cursor/rules/erebine.mdc with alwaysApply: true, .github/copilot-instructions.md, or HERMES.md for the Hermes agent respectively). pi's bundle carries its own .pi/APPEND_SYSTEM.md, which pi appends to its default system prompt; Cline's carries .cline/rules/erebine.md, which Cline reads as project context. Without the companion, the client will sometimes ask you about workspace state instead of calling the Erebine tools to retrieve it; with the companion, tool calls happen autonomously. Claude Desktop has no project-scoped rules surface and falls back to the tool descriptions returned by tools/list.

CLI alternative: the erectl mcp setup command in erectl emits the same per-client config snippets from a terminal for every supported client (Claude Code, Cursor, opencode, VS Code, OpenAI Codex, Claude Desktop, Hermes agent, pi, Cline). It fetches the workspace's models over the management API and renders the same inference provider the dashboard's Direct bundle carries for opencode, OpenAI Codex, VS Code, the Hermes agent, pi and Cline; pass --out-dir <dir> to write every file of a multi-file bundle, or --mcp-only for the server entry alone. The pinned and semantic-routed bundles are dashboard-only.

Configuration Examples

These are the shapes the dashboard's Client tab emits (right-column manager on the /chat page, once a specific workspace is selected). Replace the placeholders with values from your own download -- the <workspace_id> placeholder accepts either the URL-safe ws_<hex> form shown in the dashboard or the internal workspace UUID.

Claude Code

Save as .mcp.json at your project root (project-scoped MCP file).

JSON
{ "mcpServers": { "erebine": { "type": "http", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" } } } }

Cursor

Save as .cursor/mcp.json at your project root (or ~/.cursor/mcp.json for global). Cursor infers transport from the presence of url, no type field is needed on remote servers.

JSON
{ "mcpServers": { "erebine": { "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" } } } }

opencode

JSON
{ "mcp": { "erebine": { "type": "remote", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "enabled": true, "oauth": false, "timeout": 30000, "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" } } } }

oauth: false disables opencode's automatic OAuth discovery probe so it trusts the headers block as the only auth path, without it, opencode would try an OAuth round-trip on the MCP URL before falling back. timeout: 30000 raises opencode's 5-second default for the initial tools/list fetch so cold-path connects do not abort prematurely.

VS Code

Save as .vscode/mcp.json at your project root. Requires the GitHub Copilot Chat extension, VS Code's MCP client lives in Copilot Chat's agent mode.

JSON
{ "servers": { "erebine": { "type": "http", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" } } } }

OpenAI Codex

The Codex bundle is a Codex profile. Copy erebine.config.toml to ~/.codex/erebine.config.toml, start Codex with codex --profile erebine, and check that the header Codex prints reads provider: erebine. The file is complete and is copied, never merged: TOML attaches bare keys to the nearest [section] above them, and Codex writes a [tui] table at the end of ~/.codex/config.toml, so keys pasted there become [tui] settings. Codex also ignores provider keys in a project-scoped .codex/config.toml, so the provider cannot live in a repository.

TOML
# ~/.codex/erebine.config.toml -- run: codex --profile erebine model_provider = "erebine" model = "erebine/<model>" model_context_window = 131072 model_reasoning_effort = "medium" developer_instructions = """ (the Erebine tool-use guidance, inlined by the download) """ [model_providers.erebine] name = "Erebine - <workspace_id>" base_url = "https://api.erebine.ai/proj_ABC123/<workspace_id>/_direct/v1" wire_api = "responses" http_headers = { "Authorization" = "Bearer <api_key>", "X-Erebine-Augment-Corrective-Retries" = "on" } request_max_retries = 4 stream_max_retries = 10 stream_idle_timeout_ms = 300000 [mcp_servers.erebine] url = "https://api.erebine.ai/proj_ABC123/v1/mcp" enabled = true startup_timeout_sec = 30 tool_timeout_sec = 60 http_headers = { "Authorization" = "Bearer <api_key>", "X-Erebine-Workspace" = "<workspace_id>" }

Switch models with codex --model <id> or by editing model; the bundle README lists every id the workspace serves, and Codex's /model picker lists only its own catalog. The "Model metadata not found" warning is expected for custom model ids, and a context window above 272000 is clamped to 272000 by Codex's fallback metadata.

Optional project table. The second file, codex-config.toml, is the [mcp_servers.erebine] table alone. Append it to .codex/config.toml in a project to give every Codex session in that repository the workspace tools without the profile; it is safe to append to an existing file. Add .codex/ to that project's .gitignore.

To keep the key out of the file, replace the provider's Authorization entry with env_key = "EREBINE_API_KEY" and each MCP table's with bearer_token_env_var = "EREBINE_API_KEY", then set the variable on Codex's host.

Hermes Agent

Merge the mcp_servers section into the user-level ~/.hermes/config.yaml (the Hermes agent has no project-scoped config file), then restart Hermes. The dashboard bundle additionally carries a providers.erebine entry, a named custom provider holding the workspace's OpenAI-compatible inference endpoint and its models, plus a model block that selects it with provider: custom:erebine.

YAML
# Erebine MCP server configuration for the Hermes agent. mcp_servers: erebine: url: "https://api.erebine.ai/proj_ABC123/v1/mcp" headers: Authorization: "Bearer <api_key>" X-Erebine-Workspace: "<workspace_id>"

pi

pi has no built-in MCP client. The Erebine bundle ships a project-local .pi/ folder whose extension bridges the server; .pi/erebine.json is the connection descriptor it reads. See the pi guide for the full bundle.

JSON
{ "schemaVersion": 1, "workspace": "<workspace_id>", "mcp": { "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" }, "timeoutMs": 30000 } }

Cline

Merge the mcpServers entry into the global ~/.cline/data/settings/cline_mcp_settings.json (the IDE extension, the CLI and the SDK share it; CLINE_DATA_DIR moves the data root), then restart Cline. type must be present: a URL entry without it is treated as legacy SSE. timeout is in seconds. The dashboard bundle additionally carries providers.json and models.json, which register the workspace's models as a custom provider. See the Cline guide for the full bundle.

JSON
{ "mcpServers": { "erebine": { "type": "streamableHttp", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" }, "timeout": 60, "disabled": false, "autoApprove": [] } } }

Tools

Twenty-five tools ship in the default catalog, grouped by erebine.<namespace>. Most are read-only; a handful persist into the pinned workspace's knowledge graph or artifact store. Four more route into the governed EEM execution surface but stay hidden until MCP exec is enabled (see Governed Execution below). Every tool a key can see is advertised on the standard MCP tools/list response and dispatched via tools/call. The server also answers the standard ping JSON-RPC method, useful as a lightweight client-side health probe.

memory.*

ToolDescription
erebine.memory.search Semantic search across workspace content (memories, documents, artifacts, decisions, milestones).
erebine.memory.recall Recall workspace memories matching a query (semantic when an embedder is configured, chronological otherwise).
erebine.memory.save write Persist a workspace memory entry. The memory lands in the pinned workspace and surfaces in subsequent recall and semantic searches.

workspace.*

ToolDescription
erebine.workspace.list List workspaces in the authenticated project.
erebine.workspace.get Return the workspace pinned to the connection.
erebine.session.init Initialize a session and resolve the workspace binding for this connection (useful for clients that do not pass the workspace header on every call).

artifact.*

ToolDescription
erebine.artifact.create write Persist a workspace-scoped artifact. Returns {artifact_id, identifier, version, status}.
erebine.artifact.update write Write a new version of an existing artifact. The artifact must belong to the calling workspace.
erebine.artifact.read Read one artifact by id. Content over 1 MiB returns metadata only with content_truncated: true.
erebine.artifact.list List artifacts visible to the calling workspace. Optional chat_id narrows to a single chat; filter by artifact_type; paginate with limit and offset.

intelligence.*

ToolDescription
erebine.intelligence.brief Structured project-state briefing: decisions, blockers, milestones, connections, memories.
erebine.intelligence.timeline Project milestone timeline with optional type, date-range, and related-decision filters.
erebine.intelligence.decisions Search tracked project decisions (semantic when configured, chronological otherwise).
erebine.intelligence.analyze Synthesize a markdown brief of workspace context (documents, memories, artifacts, recent chats).
erebine.intelligence.graph Composite read of the workspace knowledge graph: decisions and milestones as nodes, relations as edges.
erebine.intelligence.relate write Create a typed relationship between two existing workspace entities. Both endpoints must already exist.
erebine.intelligence.track_decision write Record a load-bearing project decision in the workspace knowledge graph.
erebine.intelligence.track_milestone write Record a completed project milestone in the workspace timeline.

calc.* & research.*

ToolDescription
erebine.calc.evaluate Evaluate a math expression server-side. Deterministic; no external calls.
erebine.research.web_search Web search via the router's configured search backend.
erebine.research.fetch_url HTTP fetch with text and PDF extraction. Honours robots.txt; size-capped.
erebine.research.inspect_site Single-URL HTML and CSS inspection: palette, typography, layout structure.

code.*

ToolDescription
erebine.code.search GitHub code search via the router's configured GitHub token.
erebine.code.repo_overview Full GitHub repository overview: metadata, languages, README, file tree, recent commits.
erebine.code.repo_read Read specific files or list a directory inside a GitHub repository.

exec.*

ToolDescription
erebine.exec.invoke write Asynchronously invoke a EEM-advertised tool. Returns {invocation_id, status, approval_url?} immediately; poll until terminal.
erebine.exec.invoke_blocking write Streaming variant of invoke: completes in one round-trip and streams progress while running.
erebine.exec.poll Fetch the current state of an in-flight invocation by id.
erebine.exec.cancel Request cancellation of an in-flight invocation. Idempotent.

Example: persist a memory

JSON
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "erebine.memory.save", "arguments": { "content": "Shipped MCP M8 with sampling-based approvals.", "category": "decision" } } }

Example: invoke a EEM tool

The tool_name below is illustrative -- no deploy.staging EEM tool ships by default. Substitute the name of a EEM tool your operator has enrolled.

JSON
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "erebine.exec.invoke", "arguments": { "tool_name": "deploy.staging", "arguments": { "service": "router", "ref": "main" } } } }

Catalog Tiers

Pick how much of the tool catalog this connection exposes. The Client tab on the /chat page and the API Keys create form both surface the same picker; the chosen tier is carried on the API key and applied to every tools/list response served against it.

TierWhat it admits
Core (10 tools) Read-only baseline: workspace lookup, memory recall and save, calculator, session init, web research.
Exec (14 tools) Core plus governed EEM execution (exec.invoke, exec.poll, exec.cancel, exec.invoke_blocking).
Intel (25 tools) Core plus intelligence: knowledge graph, decisions, milestones, artifacts, GitHub code reads.
All (25 tools) Full erebine.* catalog. The default for new keys. The four erebine.exec.* tools stay hidden until MCP exec is enabled, so a new key sees 25; pick a narrower tier when you want to expose only what a given client needs.

Tools above the selected tier never appear in tools/list and are rejected at tools/call. Want to broaden or narrow a key later? Mint a fresh key at the new tier -- each Client tab download rotates the workspace key in place.

Governed Execution

The erebine.exec.* tools front the router's execution-plane mesh (EEM). EEM tools cross a different trust boundary than the read and write workspace tools above, a EEM tool can deploy code, run shell commands, or touch other services, so the router gates them more carefully.

Approvals you can see

When a target EEM tool requires explicit human approval, erebine.exec.invoke returns an approval_url alongside the invocation_id. Your editor surfaces the URL; click it, approve in your browser, and erebine.exec.poll walks through awaiting_approval into running once the gate clears.

Clients that advertise the MCP sampling capability can skip the browser entirely: the server prompts your editor's model to summarise the call and reply with APPROVE or DENY. Clients that advertise elicitation get a workspace-binding prompt the same way, no out-of-band confirmation step needed.

Destructive opt-in

Destructive EEM tools (deletes, irreversible operations) are hidden from tools/list by default. The API Keys create form has a Allow destructive EEM tools switch; keys minted with it on see destructive entries, keys minted without it never do.

Idempotent retries

Each erebine.exec.invoke call carries an idempotency key derived from the API key, the MCP session, the tool name, and the canonical argument shape. A duplicate request within the idempotency window returns the original invocation_id instead of creating a new one, so noisy client retries do not trigger a second deploy.

Streaming vs. polling

Use erebine.exec.invoke_blocking when your client can stream a long-running response; the call completes in one round-trip and progress events arrive on the same stream. Use the classic invoke / poll pair when streaming is awkward or your client prefers short-lived requests.

Prompts

MCP prompts are server-authored, user-triggered context primers. Clients surface them as slash commands (Claude Code, opencode, VS Code Copilot) or @-mentions (Cursor). Invoke a prompt to inject a pre-built block of messages into the conversation, equivalent to "one keystroke = run this tool sequence and paste the result."

Workspace binding required: every prompt resolves against the pinned workspace. If the connection has no workspace bound, the server rejects prompts/get with an MCP invalidRequest error and the canonical message "Workspace not bound. Call erebine.session.init or set X-Erebine-Workspace header." Set the header on connect, or call erebine.session.init once per session.

NameArgumentsEffectRequired tier
session.init none Primes a fresh session with the current workspace's capabilities and intelligence summary. Core
brief none Intelligence brief plus 5 most recent decisions. Intel
onboard topic (required) Curated context pack: memories + related entities + recent activity for the topic. Intel
save-this note (required) Fill-in form pre-populated with the note + recent memory slugs as link candidates. Caller invokes x_save_memory separately. Core
mcp-loop mode (required): on | off | status Read or set this workspace's self-evolving tool guidance. status reads (any member); on/off toggle it (project owner or operator). See Self-Evolving Guidance. Core
erepress mode (required): on | off | status Read or set this workspace's lossless token compression. status reads (any member); on/off toggle it (owner only). See Erepress. Core

Per-client invocation

ClientInvocation
Claude Code/mcp__erebine__brief
opencode/erebine:brief
Cursor@erebine brief
VS Code Copilot/mcp__erebine__brief
Claude DesktopNot currently surfaced as slash commands
OpenAI CodexNot surfaced
Hermes AgentWrapper tools (mcp__erebine__list_prompts / mcp__erebine__get_prompt)
pi/erebine:brief (registered by the bundled extension)
ClineNot surfaced

When to use prompts vs. tools: prompts are user-triggered context primers (the user fires them once to prime a session). Tools are model-driven actions called during normal reasoning. If you want one keystroke to set up context, use a prompt; if you want the model to act in the loop, use a tool.

Resources

MCP resources are URI-addressable, read-only data sources. Clients attach them to context via @-mention pickers or auto-attach UIs. Use a resource when you want the model to cite workspace state by URI rather than pasting the body inline.

Resource URIs
erebine://workspace/current/brief erebine://workspace/current/recent-decisions[?since=<duration>&limit=<n>] erebine://memory/<slug> erebine://artifact/<id>
URIReturnsMIMERequired tier
workspace/current/briefAlways-current brief.text/markdownIntel
workspace/current/recent-decisionsRolling decisions feed. Query params: since (duration like 7d), limit (default 20).text/markdownIntel
memory/{slug}Single memory by slug.text/markdownCore
artifact/{id}Single artifact by id.text/markdownCore

Per-client attachment

ClientSyntax
Claude Code@erebine://memory/my-slug
opencode@erebine://memory/my-slug
Cursor@-picker
VS Code Copilot@erebine://memory/my-slug
Claude Desktop@-picker
OpenAI CodexNot surfaced
Hermes AgentWrapper tools (mcp__erebine__list_resources / mcp__erebine__read_resource)
pierebine_resource_read tool with a uri
Clineaccess_mcp_resource (older builds)

When to use resources vs. tools: resources are passive citations (the client attaches them; the model reads them). Tools are imperative reads with parameters. If you want the model to fetch state with parameters, use a tool; if you want a URI the conversation can reference, use a resource.

Security & Isolation

The MCP surface inherits every guardrail the rest of the router enforces.

Operator gating

MCP is a deployment-wide switch. On a deployment where it is off, the /v1/mcp path returns 404 and no capability is advertised. Idle sessions expire after 600 seconds by default; the deployment sets the window. The endpoint advertises the streamable transport by default; a deployment that pins the legacy transport, for clients that misbehave against streamable, does not advertise the streamable capability.

Inference scope per request

Every MCP call must present an API key that carries the inference scope. The scope check happens at admission, before any tool dispatcher runs. Keys scoped only to management or read-only surfaces cannot be used to reach MCP, even with the right URL.

Tool exposure gates

On top of the catalog tier above, two independent workspace controls decide which tools a key sees in tools/list. Both must admit a tool for it to appear.

  • allow_mcp_exec (default false) gates the whole erebine.exec.* namespace. While it is off, the four governed EEM exec tools are hidden from tools/list and rejected at tools/call -- which is why a new key sees 25 rather than the full catalog.
  • default_tool_names, when non-empty, is an allowlist of canonical x_* names. The Settings tab auto-populates it from the tools a workspace actually uses, and any canonical name absent from a non-empty list is hidden. An empty list means "no filter" and admits every tool the other gates allow. x_session_init, x_mcp_evolution_set, and x_erepress_set are exempt: they have no chat surface to seed the list, so the allowlist never suppresses them.

The two gates are independent, so turning on allow_mcp_exec is necessary but not sufficient. If default_tool_names is non-empty and omits the x_exec_* names, the exec tools stay hidden even with MCP exec enabled; add those names to the allowlist (or clear it) to expose them.

Workspace pinning with cross-project verification

The X-Erebine-Workspace header pins each MCP connection to exactly one workspace. The header accepts either the URL-safe external identifier (ws_<hex>, the form the dashboard surfaces in chat URLs, the workspace navigator, and the Client tab) or the internal workspace UUID. Either way, the router resolves the value to a workspace row and then runs two independent verifications before accepting the pin: the workspace must belong to the same project the authenticated API key is scoped to (the cross-project membership check) and must sit in the API key's allowed-workspace list when that list is set. A key cannot be tricked into addressing a workspace it does not own, even if the identifier is technically valid for some other project on the platform.

Rotation on download

Every Client tab download mints a fresh API key for the workspace and revokes any prior active key with the same name. Leaked or stale bundles stop working the moment a new bundle for the same workspace is downloaded.

Per-client capability matrix

Each MCP client supports a different subset of the protocol surfaces. The matrix below is hand-maintained against vendor docs and is re-verified periodically; vendor support for sampling, elicitation, and roots changes faster than most of the protocol, so treat the cells as a snapshot rather than a contract.

Clienttoolspromptsresourcessamplingelicitationroots
Claude Codeyesyes (slash)yes (@)noyesyes
opencodeyesyes (slash)yes (@)nonono
Cursoryesyes (@)nonoyesyes
VS Code Copilotyesyes (slash)yes (@)yesyesyes
Claude Desktopyesyesyes (@)nonoyes
OpenAI Codexyesnoyes (@)noyesno
Hermes Agentyesyes (wrapper tools)yes (wrapper tools)yesform-modeno
piyes (extension)yes (slash)yes (read tool)nonono
Clineyesnopartial (access_mcp_resource)nonono