Skip to content

A self-improving RLM agent for coding workflows and long-running autonomous tasks.

Rust

add mcp integrations authoring guide (#283)

kt7362232fd141
diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index a84187acad..6b4704acac 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -353,6 +353,8 @@ def __getattr__(name): # so `import acme; await acme.<tool>(...)` works
The base class connects with the official `mcp` SDK, injects the bearer token from `auth.json`, and binds the server's tools as async methods. Use `await acme.call_tool("name", {...})` for tools whose names aren't valid Python identifiers, or a static `bearerTokenEnvVar` instead of OAuth.
+See [docs/mcp-integrations.md](docs/mcp-integrations.md) for the full authoring guide (package layout, auth options, the `McpIntegration` API, and caveats).
+
### Extensions
<p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
diff --git a/packages/coding-agent/docs/docs.json b/packages/coding-agent/docs/docs.json
index 3bbe242ba3..6cee553ea3 100644
--- a/packages/coding-agent/docs/docs.json
+++ b/packages/coding-agent/docs/docs.json
@@ -48,6 +48,10 @@
"title": "Skills",
"path": "skills.md"
},
+ {
+ "title": "MCP Integrations",
+ "path": "mcp-integrations.md"
+ },
{
"title": "Prompt Templates",
"path": "prompt-templates.md"
diff --git a/packages/coding-agent/docs/mcp-integrations.md b/packages/coding-agent/docs/mcp-integrations.md
new file mode 100644
index 0000000000..037bc5dca9
--- /dev/null
+++ b/packages/coding-agent/docs/mcp-integrations.md
@@ -0,0 +1,250 @@
+# MCP Integrations
+
+Connect external services (Linear, Notion, …) to Prime Agent over the
+[Model Context Protocol](https://modelcontextprotocol.io).
+
+Consistent with Prime Agent's single-tool design, MCP integrations are **not**
+exposed as new agent tools. Each integration is a [Python-backed skill](skills.md)
+that the model imports and calls from the IPython kernel:
+
+```python
+import linear
+issues = await linear.list_issues(team="Engineering")
+```
+
+The MCP connection runs inside the kernel via the official `mcp` Python SDK. The
+host's only jobs are interactive login (browser OAuth) and minting/refreshing
+credentials in `auth.json`.
+
+## Table of Contents
+
+- [Using a built-in integration](#using-a-built-in-integration)
+- [How a call works](#how-a-call-works)
+- [Authoring your own integration](#authoring-your-own-integration)
+ - [1. Declare the server](#1-declare-the-server)
+ - [2. Ship the skill package](#2-ship-the-skill-package)
+ - [Authentication](#authentication)
+- [The `McpIntegration` API](#the-mcpintegration-api)
+- [Enable-by-login lifecycle](#enable-by-login-lifecycle)
+- [Caveats](#caveats)
+
+## Using a built-in integration
+
+Built-in integrations (Linear, Notion) ship **disabled**. Logging in enables them:
+
+- Open `/login`, switch to the **Services** tab, pick the integration, and
+ complete OAuth in the browser. `/mcp login <name>` does the same from the CLI.
+- Once connected, the integration's skill becomes visible to the model and is
+ auto-imported into the kernel.
+- `/mcp` lists integrations and connection status; `/mcp logout <name>`
+ disconnects.
+
+Credentials are stored once in `~/.prime/agent/auth.json` under `mcp:<name>`.
+Enablement is derived from whether valid credentials exist — there is no separate
+on/off switch.
+
+## How a call works
+
+The tool set is defined by the **server**, not the skill, so discover before you
+call — don't assume tool names or arguments:
+
+```python
+import linear
+
+# 1. Discover available tools
+for tool in await linear.list_tools():
+ print(tool["name"], "-", tool["description"])
+
+# 2. Inspect a tool's argument schema
+help(linear.list_issues) # populated once list_tools() has run
+
+# 3. Call it; keyword args match the tool's JSON Schema
+result = await linear.list_issues(team="Engineering")
+```
+
+- Every tool is an `async` method — always `await`.
+- Results are already-parsed Python: a `dict` for structured output, a string for
+ text, or a list of content blocks otherwise. No need to `json.loads` them.
+- A tool whose name isn't a valid Python identifier (e.g. Notion's `notion-search`)
+ is called via the escape hatch: `await notion.call_tool("notion-search", {...})`.
+- A call against an integration with no credentials raises `NotEnabled` (telling
+ the user to `/mcp login`); a tool that returns an error raises `McpToolError`.
+
+## Authoring your own integration
+
+An integration is a [Python skill package](skills.md#python-backed-skills) whose
+module subclasses `McpIntegration`. The built-in `linear` / `notion` packages are
+the reference implementations.
+
+### 1. Declare the server
+
+Add it under `mcpServers` in `~/.prime/agent/settings.json` (or project
+`.prime/agent/settings.json`):
+
+```jsonc
+// ~/.prime/agent/settings.json
+{
+ "mcpServers": {
+ "acme": {
+ "type": "http",
+ "url": "https://mcp.acme.com/mcp",
+ "oauth": true
+ }
+ }
+}
+```
+
+Currently only remote `"http"` servers are supported by `McpIntegration`. HTTP
+server fields:
+
+| Field | Meaning |
+|-------|---------|
+| `type` | Must be `"http"` |
+| `url` | The MCP endpoint |
+| `oauth` | `true` to use the browser OAuth flow (requires the server to support dynamic client registration) |
+| `bearerTokenEnvVar` | Name of an env var holding a static bearer token, instead of OAuth |
+| `headers` | Extra static HTTP headers sent on every request |
+| `enabled` | Set `false` to force-disable even when credentials exist |
+
+> `stdio` (local-subprocess) servers are not yet wired through to the kernel —
+> the host drops non-HTTP entries — so an integration must target an HTTP endpoint.
+
+### 2. Ship the skill package
+
+Create a skill directory (any [skills location](skills.md#locations), e.g.
+`~/.prime/agent/skills/acme/`) with the standard Python-skill layout:
+
+```
+acme/
+ SKILL.md
+ pyproject.toml
+ src/acme/__init__.py
+```
+
+`pyproject.toml` (depends on `mcp`, `httpx`, and `prime-agent-runtime`):
+
+```toml
+[project]
+name = "prime-agent-skill-acme"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = ["mcp", "httpx", "prime-agent-runtime"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/acme"]
+```
+
+`src/acme/__init__.py`:
+
+```python
+from rlm import McpIntegration
+
+class Acme(McpIntegration):
+ server = "acme" # matches the mcpServers key / auth.json `mcp:acme`
+ url = "https://mcp.acme.com/mcp"
+
+acme = Acme()
+
+# Forward bare module access (`import acme; await acme.<tool>(...)`) to the
+# instance, but NOT the names the kernel bootstrap probes — forwarding `run`
+# would make it treat the module as a callable skill and break tool dispatch.
+_RESERVED = {"run", "__wrapped__", "__call__"}
+
+def __getattr__(name):
+ if name.startswith("_") or name in _RESERVED:
+ raise AttributeError(name)
+ return getattr(acme, name)
+```
+
+The base class connects with the `mcp` SDK, resolves the URL/headers from the host
+(honoring the `mcpServers` config), injects the bearer token from `auth.json`
+(refreshing when expired), and binds the server's tools as async methods. Authoring
+is a few lines — the package above is the whole integration.
+
+### Authentication
+
+- **OAuth** (`"oauth": true`): the user runs `/login` → Services → your server (or
+ `/mcp login acme`). Works when the server supports OAuth 2.1 dynamic client
+ registration (RFC 7591); login discovers the auth server, registers a client,
+ and runs PKCE. Servers requiring a pre-registered client id are not yet
+ supported via `mcpServers`.
+- **Static bearer token** (`"bearerTokenEnvVar": "ACME_TOKEN"`): no login needed;
+ the integration is "connected" whenever that env var is set. Set the matching
+ `bearer_token_env = "ACME_TOKEN"` on the subclass.
+
+## The `McpIntegration` API
+
+Imported from `rlm` (`from rlm import McpIntegration`).
+
+Class attributes to set on your subclass:
+
+- `server: str` — required; the `mcpServers` key and `auth.json` credential id.
+- `url: str | None` — the remote endpoint (required unless you override
+ `_open_session` for a non-HTTP transport).
+- `bearer_token_env: str | None` — optional env var holding a static bearer token.
+
+Methods:
+
+- `await list_tools() -> list[dict]` — the server's tools as
+ `[{name, description, inputSchema}]`. Also populates the docstrings shown by
+ `help(integration.<tool>)`.
+- `await call_tool(name, arguments={}) -> Any` — explicit call; the escape hatch
+ for non-identifier tool names.
+- `integration.<tool>(**kwargs)` — auto-bound async method for any discovered tool.
+
+Exceptions (both importable from `rlm`):
+
+- `NotEnabled` — raised when no usable credentials exist (not logged in).
+- `McpToolError` — raised when a tool call returns a result flagged as an error.
+
+## Enable-by-login lifecycle
+
+This auth-gating applies to the **built-in** integrations (Linear, Notion):
+
+1. The built-in skill ships installed but **disabled** — excluded from the prompt
+ and not imported into the kernel — because no credentials exist.
+2. The user logs in; credentials land in `auth.json` under `mcp:<server>`.
+3. A resource reload (automatic after `/login`/`/mcp login`, or `/reload`) detects
+ the credentials, enables the skill, and the kernel installs + imports the
+ package.
+4. Logout (or losing credentials) disables it again.
+
+If you log in mid-turn, the reload is deferred — run `/reload` after the turn to
+activate the integration.
+
+**User-authored integrations are not auth-gated this way.** A skill you drop into
+a skills directory is loaded like any other skill — visible to the model and
+imported into the kernel immediately, regardless of `auth.json`. It simply fails
+at call time with `NotEnabled` until credentials exist. So make the skill's
+`SKILL.md` tell the model how to connect when a call raises `NotEnabled`, matching
+the auth mode you configured:
+
+- **OAuth** (`"oauth": true`): instruct the user to run `/mcp login <server>` (or
+ `/login` → Services). `/mcp login` only works for OAuth servers.
+- **Bearer token** (`bearerTokenEnvVar`): instruct the user to set that env var —
+ do *not* point them at `/mcp login`, which has no provider for a bearer-only
+ server and reports "Unknown MCP integration".
+
+## Caveats
+
+- **Discover before assuming.** Tool names and argument schemas come from the
+ server and can change; call `list_tools()` / `help()` rather than hardcoding.
+- **Custom kernel + name collisions.** The kernel import name is the `server`
+ value. On a custom `PRIME_AGENT_KERNEL_PYTHON` that already has an unrelated PyPI
+ package of the same name (e.g. `notion`), `import <name>` may resolve to that
+ package instead. Use the default managed kernel venv to avoid this.
+- **Overriding a built-in name.** Declaring an `mcpServers` entry whose key matches
+ a built-in (e.g. `linear`) with a custom `url` points the integration at your
+ URL. A previously stored official credential is *not* reused for the override, to
+ avoid sending the official token to your endpoint. Authenticate such an override
+ via `bearerTokenEnvVar` only — OAuth credentials are not honored for a
+ catalog-name override. (Use a name that isn't a built-in to get OAuth.)
+- **Multi-session daemon.** OAuth provider registration is process-global; a
+ user-declared server unique to one daemon session is re-registered on that
+ session's next reload.
+
+See also: [Skills](skills.md), [Settings](settings.md).