AI Integration

The %mcp desk is pre-installed in the Groundwire pill. It provides a Model Context Protocol server that works with Claude Code, OpenCode, Codex, and other MCP-compatible agents.

Prerequisites

A running Groundwire ship (see Guide)
Your ship’s HTTP port (usually 8080)
Your ship’s login code (type +code in the dojo)

Authenticate with your ship and save the session cookie:

Find the set-cookie header in the response. It looks like:

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

Save this value — you’ll need it below.

Step 2 — Register the MCP server

Claude Code

claude mcp add --transport http urbit \
http://localhost:8080/mcp \
--header "Cookie: urbauth-~your-ship=0v3..." \
--scope user

Replace ~your-ship and the cookie value with your actual values. The --scope user flag makes it available across all projects.

OpenCode

Add to your OpenCode MCP config (typically ~/.config/opencode/config.json):

{
"mcpServers": {
"urbit": {
"type": "http",
"url": "http://localhost:8080/mcp",
"headers": {
"Cookie": "urbauth-~your-ship=0v3..."
}
}
}
}

Codex

Codex requires the mcp-proxy bridge. Install it with uvx mcp-proxy, then add to ~/.codex/config.toml:

[mcp_servers.urbit]
command = "uvx"
args = [
"mcp-proxy",
"--transport", "streamablehttp",
"--headers", "Cookie",
"urbauth-~your-ship=0v3...",
"http://localhost:8080/mcp"
]

Available tools

Once connected, your AI assistant can interact with your ship. The default tools include:

Tool	Description
`get-file`	Read a file from Clay
`insert-file`	Write a file to Clay
`list-files`	List files in a desk
`commit-desk`	Commit changes to a desk
`build-file`	Compile a Hoon file
`scry`	Scry into any agent or vane
`poke-our-agent`	Poke an agent
`run-tests`	Run tests
`new-desk` / `mount-desk`	Create and mount desks
`install-app` / `nuke-agent` / `revive-agent`	Manage agents
`add-mcp-tool`	Ask your AI to create new tools

Example usage

In Claude Code or OpenCode, just ask naturally:

“List the files on the %groundwire desk”
“Read the file /app/spv-wallet.hoon from %spv-wallet”
“Scry for the current block height from %spv-wallet”
“Create a new tool that checks my wallet balance”

Prompts & Resources

MCP prompts are available as slash commands in Claude Code:

/mcp__urbit__commit-desk mcp

Reference ship resources with @ mentions:

@urbit:beam:///base/sys/hoon/hoon
@urbit:https://docs.urbit.org/llms.txt

Adding custom tools

You can ask your AI assistant to create new MCP tools. Just describe what you want and it will write a Hoon thread and register it. Tools are threads with the signature:

$-((map @t argument:tool:mcp) shed:khan)

Notes

The session cookie expires periodically. If your AI loses connection, re-authenticate with curl and update the cookie.
Replace localhost:8080 with your actual host and port if different.
The MCP server runs on the %mcp desk which is pre-installed in the Groundwire pill.