Skip to content
Sign in

mcp-server

v0.7.1

MCP 2025-06-18 Streamable HTTP server for the iii engine — iii_call / iii_observe gateway tools, per-session observers, skills from iii-directory. Runs behind rbac-proxy.

license: Apache-2.0agentsbridgehttpmcpmodel-context-protocol

Install

bash
iii trigger compose::add worker=mcp-server@0.7.1

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

iii-config.yaml
- allowed_origins:

  api_path: /mcp
  max_buffered_observations: 500
  max_observers_per_session: 100
  max_sessions: 16
  session_idle_ttl_secs: 1800

mcp-server

Formerly the mcp worker; renamed so its job is clear from its name.

Model Context Protocol (MCP) server for the iii engine, as a single Rust binary worker. It serves MCP 2025-06-18 over Streamable HTTP (POST, GET and DELETE on /mcp, through the http worker) and gives any MCP client (Claude Code, Codex, OpenCode, Cursor, ...) the whole engine through twelve tools:

  • iii_call calls any function by id;
  • iii_secret_store stores a credential in the secrets vault and returns a secret://NAME reference for the agent to pass on instead of the value;
  • iii_observe observes a function: each matching invocation becomes an observation, buffered in the client's MCP session and read with iii_observations_poll, or handed to a target function the engine runs; iii_observations_sse streams observations on the session's GET stream instead;
  • agent profiles and skills come from the iii-directory worker.

It runs behind rbac-proxy, so RBAC decides what MCP clients may call and observe, and refuses to start otherwise.

Setup

Five steps. The first four are one-time; commands assume a compose project in the default namespace.

1. Add the workers

iii call compose::add worker=mcp-server

mcp-server declares http, rbac-proxy and secrets as dependencies, so they come with it.

The http worker listens on every interface (0.0.0.0) by default, and mcp-server refuses to serve an endpoint other machines can reach. Bind it to loopback (its configuration entry is default-http; iii call http::configuration-id names it in other namespaces):

iii call configuration::get --json '{"id": "default-http"}'
# then set the same value with "host": "127.0.0.1"
iii call configuration::set --json '{"id": "default-http", "value": { ..., "host": "127.0.0.1" }}'

mcp-server will not start yet: it is not behind rbac-proxy until step 4.

2. Provide an auth function

rbac-proxy authenticates every connection by calling your auth function (rbac.auth_function_id); with none configured it refuses everything. It receives { headers, query_params, ip_address } and returns the session's grants, or throws to refuse. The smallest useful one checks a shared bearer token. As a Node worker (workers/mcp-auth/index.mjs, npm i iii-sdk):

import { timingSafeEqual } from 'node:crypto'
import { registerWorker } from 'iii-sdk'

const iii = registerWorker(process.env.III_URL, { workerName: 'mcp-auth' })
const expected = Buffer.from(process.env.MCP_TOKEN ?? '')

iii.registerFunction(
  'mcp-auth::authenticate',
  async ({ headers = {} }) => {
    const auth = Object.entries(headers).find(([k]) => k.toLowerCase() === 'authorization')?.[1]
    const token = Buffer.from(String(auth ?? '').replace(/^Bearer\s+/i, ''))
    if (expected.length < 32 || token.length !== expected.length || !timingSafeEqual(token, expected)) {
      throw new Error('invalid token')
    }
    return {
      allowed_functions: [],
      allow_function_registration: true,
      // mcp-server keeps its own name, so compose sees it start.
      worker_names: ['mcp-server'],
      // Agents store secrets; nothing on the MCP server may read one back.
      forbidden_functions: ['secrets::resolve'],
    }
  },
  // It sees bearer tokens: nothing may observe it.
  { observable: false },
)

Put a long random token in your project's .env (openssl rand -hex 32):

MCP_TOKEN=<token>

and add the worker to worker-compose.yaml:

  mcp-auth:
    worker: path://./workers/mcp-auth
    env_file: [./.env]
    scripts:
      run: node index.mjs

3. Point rbac-proxy at it

rbac-proxy's settings live in the configuration worker. In a compose project the entry is <namespace>-rbac-proxy (default-rbac-proxy):

iii call configuration::set --json '{
  "id": "default-rbac-proxy",
  "value": {
    "host": "127.0.0.1",
    "port": 49200,
    "engine_url": "ws://127.0.0.1:49134",
    "rbac": {
      "auth_function_id": "mcp-auth::authenticate",
      "expose_endpoints": ["match(\"/\")", "match(\"/ws/channels/*\")", "match(\"/otel\")"],
      "expose_functions": ["match(\"*\")"]
    }
  }
}'

rbac-proxy applies it live. Two lists decide what gets through:

  • expose_endpoints is which of the engine's endpoints rbac-proxy serves. It serves none until you list them. mcp-server needs / to connect at all; /otel carries its logs and traces (without it the log shows HTTP error: 403 Forbidden and no telemetry is exported); keep /ws/channels/* for functions that stream.
  • expose_functions is what MCP clients may reach: match("*") is everything; narrow it (match("orders::*"), metadata: { public: true }, ...) to limit agents. Keep secrets::set in it for iii_secret_store, and keep secrets::resolve out: it returns a secret's value, so any agent on the MCP server could read every secret. match("*") and match("secrets::*") both include it, which is why the auth function above forbids it.

See rbac-proxy for the rules, scoped grants and hooks. Check it with iii call rbac-proxy::status: rbac_enabled: true and the three endpoints in expose_endpoints.

4. Point mcp-server at rbac-proxy

In worker-compose.yaml, give mcp-server the proxy's address and the token:

  mcp-server:
    worker: package://api.workers.iii.dev/mcp-server
    env_file: [./.env]
    environment:
      III_MCP_ENGINE_URL: ws://127.0.0.1:49200

and in .env, III_TOKEN is the token mcp-server sends (the same value as MCP_TOKEN):

III_TOKEN=<token>

Then restart it: iii call compose::restart container=mcp-server.

Use III_MCP_ENGINE_URL, not III_URL: compose sets III_URL to the engine itself for every worker.

5. Connect a client

The endpoint is the http worker's URL plus /mcp (iii call http::status reports the base, by default http://127.0.0.1:3111). For Claude Code:

claude mcp add --transport http iii http://127.0.0.1:3111/mcp

Ask the agent for iii_status: it reports "access_control": "rbac-proxy" and the rules in force.

Several MCP servers can share one http worker. Each needs:

  • its own worker name: the engine keeps one live worker per name, and a second mcp-server under the same name replaces the first. Under compose, each container's name is its worker name (compose sets III_WORKER_NAME), so run them as separate containers, for example mcp-server-team and mcp-server-ops;
  • that name in its auth function's worker_names grant, so compose sees it start (rbac-proxy lets one live session at a time hold a granted name);
  • its own api_path, and its own rbac-proxy and token to give each different rules.

Local development without RBAC

On a machine you alone use, you can skip steps 2 to 4:

  mcp-server:
    worker: package://api.workers.iii.dev/mcp-server
    environment:
      III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC: "true"

Every MCP client can then call every function on the engine; the server logs a warning and tells every client in its initialize instructions and iii_status.

The RBAC check

Before registering anything, mcp-server calls rbac-proxy::session, which rbac-proxy answers itself for every proxied connection and never forwards; a connection straight to the engine gets function_not_found.

Situation Outcome
Behind rbac-proxy Starts. If the proxy's expose_functions include match("*") and it has no auth function, it logs a warning.
Not behind rbac-proxy Refuses to start (exit 1), with the message below.
Not behind rbac-proxy, III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC=true or 1 Starts, warns in the log, initialize instructions and iii_status.
III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC set to anything else Refuses, naming the accepted values.
Behind rbac-proxy with the flag set Starts; logs at info that the flag is ignored.
The probe cannot be made (engine or proxy down, connection refused by auth, timeout) Refuses to start.
mcp: refusing to start: not behind rbac-proxy.
  The MCP server exposes iii_call and iii_observe, which can reach every function
  on this engine. It must connect through rbac-proxy so RBAC decides what MCP
  clients may do.
  Connected to: ws://127.0.0.1:49134 (rbac-proxy::session: function_not_found)
  Fix: install rbac-proxy (iii call compose::add worker=rbac-proxy), set its
  rbac.auth_function_id, and give mcp:
    III_MCP_ENGINE_URL=ws://127.0.0.1:49200   (rbac-proxy's port)
    III_TOKEN=<a token your auth function accepts>
  To run without RBAC anyway (local development only):
    III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC=true

The check guards against a misconfigured URL, not an attacker: anything that can register functions on the engine directly could register a fake rbac-proxy::session. All MCP clients share the worker's one proxied identity, so RBAC decides what "agents via MCP" may do as a whole.

Next, mcp-server reads http::status. If the http worker listens anywhere but loopback (0.0.0.0, ::, a LAN or public address), or its bind cannot be read, it refuses to start and says how to bind it to 127.0.0.1; III_MCP_DANGEROUSLY_ALLOW_PUBLIC_HTTP=true (or 1) serves anyway, with a warning. The check repeats after every reload of the http worker: mcp-server observes http::on-config-change, and a rebind to a public address withdraws the /mcp routes until it is back on loopback (rbac-proxy must expose http::status and http::on-config-change). The routes are served only once that observer is active: if rbac-proxy refuses it, /mcp is not served and the log says what to expose, since a later rebind would go unseen. III_MCP_DANGEROUSLY_ALLOW_PUBLIC_HTTP=true serves without it.

Interface collection (release publishing and the CI smoke) boots the worker with config.collect.yaml, which sets interface_only: true: it registers its functions and serves nothing (no /mcp route, every MCP request answered 503, no downstream call), so it starts without rbac-proxy or an http worker. It is not a way to run the server. When a check cannot read http::status (it timed out during a reload, say), the routes stay withdrawn and the check runs again after 2, 5, 10, 30 and 60 seconds, stopping at the first that reads the bind; after that, the next reload checks again.

Tools

Tool What it does
iii_call Call a function by id with a JSON payload (default {}). timeout_ms; void: true to fire and forget; the reply is compact JSON of at most max_chars (default 100000, at least 80): over it, the result's JSON text is cut so the whole reply fits, with truncated and total_chars. mcp-server:: functions (this worker's internals) are refused, as observe sources and targets too; everything else is RBAC's decision.
iii_secret_store Store a credential: name (secret://<name>), value, consumers (worker names allowed to resolve it, at least one), description. Calls secrets::set and returns only { ref, hint, fingerprint, consumers }. Storing an existing name rotates it. rbac-proxy must expose secrets::set.
iii_observe Observe a function: function_id, filters, args, capture, namespace, max_observations, expires_in_ms, and optionally target_function_id. Without a target, observations are buffered for iii_observations_poll. With one, the engine runs that function with each observation and nothing comes back to the session. Returns { observer_id, function_id, state, delivery, target_function_id? }. Needs a session.
iii_observations_sse Same arguments without target_function_id: each observation is sent on the session's GET stream as a notifications/iii/observation message, and waits in the session while no stream is open. Needs a session.
iii_observations_poll Read and remove buffered observations of poll observers, oldest first, for one observer_id or all of them; max (default 50). Returns { observations, remaining, dropped }. Needs a session.
iii_observers The session's observers with delivery, state, buffered, received, dropped (and target_function_id). Needs a session.
iii_unobserve Remove one observer, discarding its unread observations. Needs a session.
iii_status Server version, session id, the session's active_profile (default-mcp until another is activated), and access_control: rbac-proxy with its policy (the exposed globs), or disabled with a warning.
iii_list_agents, iii_get_agent Agent profiles from directory::agents::* (hidden ones with include_hidden). iii_get_agent without an id returns the default-mcp profile; with activate: true the profile becomes the session's active profile.
iii_list_skills, iii_get_skill Skills from directory::skills::* (search, prefix).

The initialize instructions tell the agent, in this order, to:

  1. load the default profile with iii_get_agent { activate: true } (no id; it reads directory::agents::get {"id": "default-mcp"} from iii-directory) and follow it. default-mcp is iii-directory's default identity rewritten for MCP clients: iii_call and the observe tools instead of agent_call and harness::*;
  2. discover the system with iii_call: directory::search_functions for candidate ids by capability, engine::functions::list, engine::workers::list, and engine::functions::info for a contract before the first call; directory::skills::index for the relevant skills (guidance documents, not one per worker), sparingly;
  3. use higher-order functions, which call other functions for it: fp::pipe chains calls worker-side (large values never pass through the agent) and fp::batch runs independent calls at once.

They also say the server cannot register functions: to add one, the agent creates or changes a worker it controls and registers it with the iii-sdk.

Engine errors come back as tool results with isError: true and the engine's code, as the MCP spec prescribes for tool execution errors, so the model reads them; JSON-RPC errors are kept for protocol errors. Unknown tool names are tool errors too.

Secrets

An agent that holds a credential stores it with iii_secret_store and passes the secret://NAME reference to the function that needs it, which resolves it through secrets::resolve if it is a listed consumer. A value is never retrievable through the MCP server: otherwise any agent connected to it could read every secret. rbac-proxy keeps secrets::resolve out (see setup step 2), and the secrets worker only resolves for listed consumers. To keep the value out of the engine's records:

  • mcp-server::handler, which receives every request body, is registered observable: false, so no observer gets a copy;
  • this worker turns off payload capture in its trace spans (III_DISABLE_TRACE_PAYLOADS=1);
  • tool results and error messages never contain the value.

The value still crosses the http worker, and anything that records request bodies there (its own traces, a proxy in front of it) can see it. The agent's model has seen it too.

Sessions and observe

initialize opens a session and returns its id in the Mcp-Session-Id response header; clients send it back on every request. An unknown or expired id gets 404, which tells the client to initialize again. DELETE /mcp with the header ends the session (200; 404 if unknown, 400 without the header). Requests without the header work for every tool except the observe ones.

An observer delivers in one of three ways:

  • poll (iii_observe): the engine sends each observation to mcp-server::observed, one sink for the worker, which routes it to its session by observer_id; the client reads it with iii_observations_poll;
  • sse (iii_observations_sse): through the same sink, then out on the session's GET /mcp stream, each with an SSE event id. They stay in the session after they are written, so a client that reconnects with Last-Event-ID gets every observation after that id: a dropped connection loses nothing. A GET without it gets only what no stream wrote yet. Nothing is written on a schedule: a quiet stream is ended by the http worker's idle timeout (default_timeout, 30 s), and the client reconnects. If the cap dropped observations the client never got, the replay starts with a notifications/iii/observations_dropped message naming the ids. A stream more than max_buffered_observations behind is closed rather than queued without bound; the client resumes with Last-Event-ID;
  • target (iii_observe with target_function_id): the engine runs that function with each observation; nothing reaches the session.

Limits and cleanup:

  • at most max_sessions sessions (default 16) and max_observers_per_session observers (default 100). At the limit, initialize ends the session seen least recently (its client gets 404 and initializes again), so clients that never end theirs, such as headless Claude Code turns, cannot lock the server; it answers 503 only when every session holds an open SSE stream;
  • each session holds up to max_buffered_observations (default 500) across its observers; beyond that the oldest are dropped and counted;
  • the idle-session sweep, a task in mcp-server that runs once a minute, ends every session idle for session_idle_ttl_secs (default 1800) and disposes its observers; the worker also disposes every observer on shutdown;
  • an observer of a function nobody hosts yet stays pending; a refused one (bad filter, unknown capture, RBAC) is reported with the engine's code.

mcp-server::observed is public because the engine refuses a private observer target; it is marked internal and hidden from traces. The engine stamps every call a worker makes with the caller's worker id, and its own deliveries carry no stamp, so the sink accepts a stamped delivery only from the worker that hosts the observed function. Another worker calling it with a forged observer_id is dropped.

Origin

The MCP spec requires validating Origin, so a web page cannot drive a local MCP server through the browser: no Origin header (CLI and SDK clients) and loopback origins (localhost, *.localhost, 127.0.0.1, [::1], any port) pass, exact entries in allowed_origins pass, anything else gets 403.

Resources

Skills are resources at iii://<id> (resources/list, resources/read, resources/templates/list), read from iii-directory. The server offers no prompts.

Configuration

config.yaml (optional; a missing or malformed file falls back to the defaults with a warning):

api_path: "/mcp"
allowed_origins: []
session_idle_ttl_secs: 1800
max_sessions: 16
max_observers_per_session: 100
max_buffered_observations: 500
Environment Meaning
III_MCP_ENGINE_URL rbac-proxy's WebSocket URL (wins over III_URL; --url wins over both)
III_TOKEN Bearer token sent to rbac-proxy's auth function
III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC true or 1 to start without rbac-proxy (local development only)
III_MCP_DANGEROUSLY_ALLOW_PUBLIC_HTTP true or 1 to serve on an http worker that is not bound to loopback

Development

cargo test --lib                       # unit tests, no engine needed
III_ENGINE_WS_URL=ws://127.0.0.1:49134 \
III_ENGINE_HTTP_URL=http://127.0.0.1:3111/mcp \
  cargo test --test bdd                # end to end against a running engine

The BDD harness connects straight to the engine, so it runs in the mode III_MCP_DANGEROUSLY_RUN_WITHOUT_RBAC would select.

Search the registry

Find workers, kits and executables, or jump to a page.