Urbit MCP

A general-purpose Model Context Protocol interface for Urbit.

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

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

Prompts (slash commands)

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

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 <your-ship-url>/vitriol "<auth-cookie>"

Manual install:

git config gpg.program /path/to/hooks/groundwire-sign
git config commit.gpgsign true
git config groundwire.sign-endpoint <your-ship-url>/vitriol
git config groundwire.sign-token "<auth-cookie>"

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