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