Urbit MCP

A fork of gwbtc/urbit-mcp by Groundwire

A general-purpose Model Context Protocol interface for Urbit.

The %mcp desk ships as a single integrated control plane with three pieces:

1. Native MCP server at /mcp — runs Hoon-defined tools, prompts and resources directly on your ship.
2. MCP proxy at /apps/mcp/mcp — aggregates the native server plus any number of remote MCP / OpenAPI / Google Discovery upstreams behind a single endpoint, with per-server tool filtering and OAuth 2.0 + PKCE token management. OpenAPI and Discovery spec docs are dynamically converted to MCP tool calls.
3. Operator console at /apps/mcp/ — a web UI for configuring upstreams, OAuth providers, the API key, and inspecting tools.

Both /mcp and /apps/mcp/mcp authenticate with the same X-Api-Key header. A random key is generated on first install and can be regenerated, set, or cleared from the operator console.

Quickstart

The fastest way to get a running Urbit with MCP configured is to install Groundwire. The onboarding script will automatically configure your ship for Codex, Claude Code, and Opencode.

curl -fsSL https://groundwire.io/install.sh | bash

If you don’t need your LLM to have a self-custodied decentralized ID, you can skip the attestation flow.

curl -fsSL https://groundwire.io/install.sh | bash -s -- --skip-attestation

Note that this will configure a hard-coded cookie which will eventually expire. Your ship’s local Codex and Opencode config files link to this README, which has instructions for getting a new cookie.

Build from source

1. Build and Install

• Requires a running Urbit ship, real or fake, running on a machine you have terminal access to.
• Requires Zig 0.15 or newer. Make sure zig version works.

Create and mount the desk on your Urbit ship:

> |new-desk %mcp
> |mount %mcp

In the urbit-mcp folder, run zig build. By default this will install dependencies into /zig-out in this folder. Use --prefix/-p to choose another output directory, and use the -Ddesk option to additionally replace the contents of your ship’s desk with your source desk.

$ cd urbit-mcp
$ zig build -Ddesk=~/path/to/zod/mcp

> |commit %mcp
> |install our %mcp

This installs four agents on your ship:

• %mcp-server — native MCP server bound to /mcp
• %mcp-proxy — aggregator bound to /apps/mcp/api and /apps/mcp/mcp
• %mcp-fileserver — serves the operator UI at /apps/mcp/
• %oauth — OAuth 2.0 + PKCE provider/grant manager

2. Open the operator console

Visit http://localhost:PORT/apps/mcp/.

The console has three tabs:

• Endpoint — the proxy aggregate URL and your X-Api-Key. Buttons to generate a random key, set a custom one, copy, or clear it. The page also shows a claude mcp add snippet pre-filled with your ship name and key.
• Upstreams — configured remote servers. The native server is registered automatically and tagged BUILT-IN. Add your own MCP servers, OpenAPI REST APIs, or Google Discovery documents. Each upstream can be linked to an OAuth provider for automatic token injection, and you can allow- or block-list individual tools.
• OAuth — manage OAuth 2.0 + PKCE providers. Connect / disconnect grants, edit endpoints, store client secrets (the secret is never returned to the browser; leaving the field blank in an edit preserves the saved value). OAuth providers can be assigned to upstreams and automatically renew expired sessions.

3A. Register with Claude Code

In the Endpoint tab, click GEN to mint an API key (or SET to use your own). Then copy the snippet shown under CLAUDE CLI, which will look like:

claude mcp add --transport http zod \
  http://localhost:8080/apps/mcp/mcp \
  --header "X-Api-Key: "

3B. Register with Codex

Codex connects directly to the Streamable HTTP endpoint. Add this to ~/.codex/config.toml:

[mcp_servers.zod]
url = "http://localhost:8080/apps/mcp/mcp"
http_headers = { "X-Api-Key" = "" }

Usage

OAuth tokens for automations

GET /apps/mcp/api/oauth/token/{provider-id} returns the complete stored OAuth grant for a provider, such as asana. Authenticate with the same X-Api-Key used by the MCP endpoints; a ship login cookie alone does not authorize this route.

curl --fail --silent --show-error \
  -H "X-Api-Key: $MCP_API_KEY" \
  "https://your-ship.example/apps/mcp/api/oauth/token/asana"

{
  "providerId": "asana",
  "accessToken": "",
  "refreshToken": "",
  "tokenType": "Bearer",
  "scopes": "",
  "expiresAt": "~2026.10.20..12.00.00..0000"
}

refreshToken and expiresAt are null when absent. expiresAt uses the desk’s Urbit @da date format. This endpoint returns the grant as stored, including expired grants, without refreshing it. OAuth client configuration is separate from the grant. The ship refreshes grants automatically; fetch the grant when the automation needs it. Responses include Cache-Control: no-store.

The endpoint returns 401 for a missing or invalid API key, 404 when no grant can be read for the provider, and 405 for methods other than GET.

Tools

Just ask! You can see the default tools here.

You can ask your LLM to add new Tools. Give it a description (and ideally, examples) and it will do its best, or provide a Hoon thread for it to adapt to run in %mcp-server. Threads in %mcp-server must be of signature $-((map @t argument:tool:mcp) shed:khan).

Prompts (slash commands)

Depending on your agent harness, MCP prompts for most default tools may be available as slash commands, e.g. /mcp__zod__.

Running these will append a prompt snippet to the conversation and call out to the LLM provider. You can ask your LLM to add new Prompts.

Resources (@ mentions)

Depending on your agent harness, MCP resources may be referenced with an @ mention to pull their contents into the context window.

@zod:https://docs.urbit.org/llms.txt

You can ask your LLM to add new Resources by providing an https:// URI to a public webpage or a beam:// URI to a file in your Urbit’s Clay filesystem.

Contributing

This repo requires commits to be signed with a Groundwire identity. PRs with unsigned commits will be rejected by CI.

Setup commit signing

You need an Urbit ship running the %vitriol agent.

Quick install:

./hooks/install.sh /vitriol ""

Manual install:

git config gpg.program /path/to/hooks/groundwire-sign
git config commit.gpgsign true
git config groundwire.sign-endpoint /vitriol
git config groundwire.sign-token ""

Once configured, all commits will be automatically signed with your ship’s Ed25519 networking key. The CI verifies signatures against on-chain keys via vitriol.bot.

Re-signing existing commits

If you have unsigned commits on a branch:

git rebase --exec "true" HEAD~N

(where N is the number of commits to re-sign)

Development

Build Commands

• zig build - Build /desk and dependencies into /zig-out
• zig build -p ~/path/to/output - Build into the selected install prefix
• zig build clean - Remove the install prefix
• zig build clear - Remove the install prefix and cached dependencies from .zig-cache/desk-deps
• zig build -Ddesk=~/path/to/desk - Build, clean the target desk directory, and copy the install prefix into it; supports absolute and relative paths