Urbit MCP

A general-purpose Model Context Protocol interface for Urbit.

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

2. Authentication Setup

Get your ship’s web login code from the Dojo:

> +code
lidlut-tabwed-pillex-ridrup
~zod:dojo>

Authenticate and get session cookie:

curl -i http://localhost:80/~/login -X POST -d "password=lidlut-tabwed-pillex-ridrup"

Extract the cookie from the set-cookie header, which will look like this:

urbauth-~your-ship=0v3.j2062.1prp1.qne4e.goq3h.ksudm

3a. Register with Codex

Simply add this to your ~/.codex/config.toml:

[mcp_servers.zod]
enabled = true
url = "http://localhost:80/mcp"
http_headers = { "Cookie" = "urbauth-~your-ship=0v3.j2062.1prp1.qne4e.goq3h.ksudm" }

3b. Register with Claude Code

Add the MCP server to Claude using HTTP transport:

claude mcp add --transport http zod http://localhost:80/mcp --header "Cookie: urbauth-~your-ship=0v3.j2062.1prp1.qne4e.goq3h.ksudm" --scope user

Usage

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).

Managed Aqua runs

aqua/start starts a Spider thread without waiting for it to finish. Pass desk, path (for example /ted/ph/add), and optionally arg as raw Hoon. The ship must have %aqua running with a pill loaded.

aqua/pill loads that pill. It builds a brass pill with prime and cache on, pokes it into %aqua, and returns Dojo’s output once %aqua has the pill. Pass desks to include desks besides the base desk, and base to name a base desk other than %base. The tool first checks that %aqua is running from the %base desk; if not, it returns an error that says how to start it. Building and priming a pill takes minutes.