docs
// API Reference

MCP Integration

One HTTP MCP endpoint. Ten client bundles. Twenty-nine 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 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.
  • omp, terminal coding agent; native streamable-HTTP MCP from a project .omp/mcp.json.

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). An operational workspace has no Client tab: it runs EEM tool calls and serves no inference, so connect a client from a chat workspace.

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, omp).

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 with its own API key for that client. Downloading a client again rotates that client's key and revokes the one in its older bundle; your bundles for other clients keep working.

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, .omp/mcp.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; omp's carries .omp/RULES.md, which omp applies as sticky rules. 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, omp). 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, Cline and omp; 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_DIR, CLINE_DATA_DIR and CLINE_MCP_SETTINGS_PATH move it), or add it with cline mcp add, then restart Cline. type must be present: a URL entry without it is treated as legacy SSE. timeout is in seconds. The IDE expands ${env:EREBINE_API_KEY} in a header; the CLI expands no placeholder. The dashboard bundle additionally carries providers.json and models.json, which register the workspace's tool-capable 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": [] } } }

omp

Save the entry as .omp/mcp.json at your project root, or merge it into the file that is there. type must be present: an entry without it is treated as a local stdio server. timeout is in milliseconds and bounds every tool call. The dashboard bundle additionally carries models.yml, which registers the workspace's models as a custom provider in ~/.omp/agent/models.yml, and a .omp/config.yml model role. See the omp guide for the full bundle.

JSON
{ "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json", "mcpServers": { "erebine": { "type": "http", "url": "https://api.erebine.ai/proj_ABC123/v1/mcp", "headers": { "Authorization": "Bearer <api_key>", "X-Erebine-Workspace": "<workspace_id>" }, "timeout": 60000 } } }

Tools

Twenty-nine 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 Erebine Execution Manager (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 Confirm and pin the workspace this connection is already bound to (through the header or client roots). It cannot create the first binding.

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.
erebine.artifact.generate_image write Generate or edit images on the workspace's image generation endpoint. Each image is stored as a workspace artifact with its license record and returned with a download link valid for 60 minutes, followed by an MCP image content block (a PNG over 3.75 MB is attached downscaled; an image that cannot be brought under that limit is not attached, and the link still serves the full file). references takes artifact ids of images in the workspace. Spends the project's credit: needs the research scope and draws on the research rate limit. Present only where image generation is available and the workspace's Images switch (on by default) is on; switched off, a call returns a plain result saying so. See x_generate_image.

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). Markdown by default; format: "json" returns the page as one JSON object.
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.trace Read the workspace's plan in one call: each goal with its milestones in order, and for each milestone its state, whether it is ready to start, its acceptance criteria, its links to other plan items, what it waits on, the decisions it implements, the memories that record how it was done, its commits and the agents that worked on it. Markdown by default; format: "json" returns one JSON object. closed_only: true reads the reached and dropped goals instead, newest first, a page at a time: pass the result's page.next_cursor back as cursor for the next page. Erebine Desktop Code draws this plan as Trace and as the plan board.
erebine.intelligence.relate write Create a typed relationship between two existing workspace entities. Both endpoints must already exist.
erebine.intelligence.link write Add or remove one link between two items of the plan, or between a plan item and a decision: runs_after, blocked_by, informs or decision. A milestone is ready once everything it runs after or is blocked by is reached or abandoned. A link that would close a loop is refused.
erebine.intelligence.suggest_links Propose links between the cards of the plan, and from cards to decisions, each with a score and a reason. methods names how to look, any of embedding, ranking, system1 and llm; a method the workspace has no endpoint for is skipped and reported, and an empty array returns only which methods can run. system1 is reported with calibrated: false and its measured accuracy: its link suggestions are not yet calibrated. A pair that is already linked, and a link that would close a loop, are never suggested. Nothing is saved: accept a suggestion with erebine.intelligence.link. Each method is billed as the embedding, scoring, System 1 or inference requests it makes.
erebine.intelligence.enhance Propose text for one field of a plan card: its description or its acceptance_criteria, written from the card, its goal, the cards and decisions it is linked to and the project brief. model names the model to write it; left out, the workspace's inference endpoint is used. Nothing is saved: keep a proposal with erebine.intelligence.update_milestone. One inference request billed to the project.
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. With status it writes planned work instead: a goal (milestone_type: "goal_set") or one of its steps (goal_id), numbered G1, M1 and so on.
erebine.intelligence.update_milestone write Update one milestone: rename it, set its state (planned, in_progress, blocked, reached, abandoned), reorder it, move it under another goal, and link the memory that records how it was done, the decisions it implements and its commits. A planned step also takes acceptance_criteria, check_criteria (mark criteria met by number) and run (who works it, whether to ask first, whether it may run beside others). Only what is sent changes.

calc.*, time.*, weather.* & research.*

ToolDescription
erebine.calc.evaluate Evaluate a math expression server-side. Deterministic; no external calls.
erebine.time.now The current time in UTC and in an IANA time zone or a place, from the server's clock, with the UTC offset, daylight saving and weekday. Needs the research scope: a place is looked up with OpenStreetMap. See x_get_time.
erebine.weather.report A sourced weather report for a place or coordinates: current conditions, the next 24 hours and 7 days, sunrise and sunset, and official alerts in the United States. Data from MET Norway and the US National Weather Service, credited in the result. Needs the research scope. See x_get_weather.
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.
erebine.research.image_search Royalty-free image search across Openverse, Wikimedia Commons, Pexels, Pixabay and Unsplash. Every result carries its license record: commercial use, required credit, whether a copy may be hosted, and a credit line. Present only where image search is enabled. See x_image_search.
erebine.research.fetch_image Download one image search result's file. A result whose license forbids a hosted copy is never downloaded; for Unsplash the call registers the use its guidelines require. The JSON license record comes first, then the file as an MCP image content block; a file over 3.75 MB is replaced by its preview rendition when that fits. Present only where image search is enabled. See x_fetch_image.

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 an 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 an EEM tool

The tool_name below is illustrative -- no deploy.staging EEM tool ships by default. Substitute the name of an 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 (14 tools) Read-only baseline: workspace lookup, memory recall and save, calculator, session init, web research, image search, time and weather.
Exec (18 tools) Core plus governed EEM execution (exec.invoke, exec.poll, exec.cancel, exec.invoke_blocking).
Intel (37 tools) Core plus intelligence: knowledge graph, decisions, milestones and the plan, artifacts and image generation, GitHub code reads, workspace toggles.
All (41 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 37; pick a narrower tier when you want to expose only what a given client needs.

Counts are upper bounds. The two image search tools appear only where image search is enabled, image generation only where it is available, the time and weather tools only where the deployment keeps them on (they are on by default), and the workspace toggles only where the deployment supports them.

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 that client's key in place.

Governed Execution

The erebine.exec.* tools front the router's execution-plane mesh of EEMs. EEM tools cross a different trust boundary than the read and write workspace tools above, an 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. Set the X-Erebine-Workspace header, or connect with a client that advertises roots support." Set the header on connect, or use a client that advertises roots; erebine.session.init needs a bound session too and cannot create the first binding.

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)
Cline/mcp:erebine:brief (IDE extension)
omp/erebine:brief (arguments as key=value)

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)
ompread tool with the resource URI

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.

Commit Attribution

Every bundle that ships a rules file asks the coding agent to sign each git commit an Erebine endpoint generates with one trailer line in the message footer:

Text
Co-Authored-By: Erebine $MODEL_NAME $ENDPOINT <noreply@erebine.ai>

$MODEL_NAME is the name of the model the agent runs as. $ENDPOINT is the Erebine endpoint that serves it: the last /-separated part of the model id the client sends, so erebine/qwen36-27b gives qwen36-27b. A commit made on a model Erebine does not serve, as in Claude Code, carries no Erebine trailer.

Commit message
Fix the login redirect loop Co-Authored-By: Erebine qwen3.6-27b qwen36-27b <noreply@erebine.ai>

The line joins the trailers the client already writes, in the message's last paragraph, so git interpret-trailers and git log --format='%(trailers:key=Co-Authored-By)' read it. A repository that prescribes its own attribution format keeps it: the agent follows the repository. To turn attribution off, delete rule 5 under Other rules from the rules file. OpenCode 1 loads the hosted rules file, so point its instructions entry at a local copy without the rule.

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 30 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 has its own API key per workspace. A Client tab download mints a fresh key for that client and revokes your prior key for the same client in the same workspace. A leaked or stale bundle stops working the moment you download that client's bundle again; your bundles for other clients keep working. The API Keys page lists each key by client name.

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
Clineyesyes (slash, IDE)partial (access_mcp_resource)nonono
ompyesyes (slash)yes (read tool)nonoyes