Skip to main content
Experimental version.This is the latest in-development version of AI-Implement. Features may change without notice and behavior is not guaranteed. Switch to the latest stable version here.
/mcp is the orchestrator’s Model Context Protocol endpoint. It lets a Claude session — and every BuildDown skill that runs in one — ask the orchestrator about itself and, for a declared few actions, act on it. The tools come from two places, merged into one list:
  • Orchestrator-native tools, served by the orchestrator process directly. They need no knowledge-graph sidecar, so they answer even on an image built without one.
  • Knowledge-graph tools (kg_*), forwarded to the bound knowledge graph. Without a bound graph, a kg_* call returns an error naming the fix.

​
How a session connects

A session authenticates with a bearer token from the MCP sign-in flow. An admin-UI session or the shared access code is never accepted at /mcp. The token resolves to an identity — email, provider, and role. Every request re-checks that identity against the same allowlist the admin UI uses, so removing someone ends their access on their next call rather than when the token expires.
Who may sign in, and whether their allowlist entry carries the user or admin role, is set on the allowlist. See Single sign-on.

​
Reads are open; writes are declared

Every allowlisted identity — user or admin — can see and call every read tool, including ones added later. There is no per-tool sign-up for reads. A write exists only if it is on a declared list, and each entry names the role it requires. That list is the entire write surface: every other mutation — allowlist edits, secrets, deploys, page grants — stays on the admin API and its UI. A caller’s role satisfies a write when it matches the entry’s role or is admin.

​
Read tools

Open to every allowlisted user. Served by the orchestrator: The bound knowledge graph adds its own read tools, open to every allowlisted user in the same way:
  • kg_hybrid_search
  • kg_search
  • kg_semantic_search
  • kg_neighbors
  • kg_path
  • kg_provenance
A given graph may expose more — the set is whatever the bound provider lists.

​
Write tools

Each requires the role shown. Served by the orchestrator:

​
When a write is refused

A caller whose role does not satisfy a write gets a tool result marked as an error, reading:
The refusal is decided on the server, so it holds even though tools/list already hides the tools a caller’s role cannot use. Every write call, allowed or refused, is logged with the actor’s email, the tool, the role, and the result. To gain the access, ask an orchestrator admin to change your allowlist entry to the admin role.

​
Admin-only skills

Two BuildDown skills perform a declared write, so both are admin-only:
  • bd-kg-refresh — rebuilds the project’s knowledge graph through the refresh rail.
  • bd-mega-kg-refresh — the local, interactive variant that iterates on the ingest before handing off to the rail.
Each calls get_session_identity first and stops before doing anything when the role is not admin. What an operator without the role sees is the skill’s own stop — it needs an admin account — and, if a write is attempted directly, the orchestrator’s forbidden: <tool> requires the admin role. The fix is the same as for any refused write: an admin changes the allowlist entry to the admin role.