Connecting Umtri's MCP to Claude Code

In the last post, we saw that Umtri is a service for recording and visualizing your project structure as a tree. This time, we’ll actually connect Umtri to Claude Code.

The technology behind this connection is MCP (Model Context Protocol). We covered the concept of MCP itself in part 6 of the vibe coding series, so here we’ll focus on the hands-on process of connecting Umtri. Setup takes just one command in the terminal.

What Changes Once You Connect Umtri

Without MCP, the AI only knows what’s inside the conversation and your open files. Once you connect Umtri’s MCP, Claude Code can read your project structure straight from Umtri and automatically add or edit nodes as it works.

	Without MCP	With Umtri MCP
What the AI can know	The conversation, open files	The Umtri tree structure too
How it works	Writes code only	Can query the tree, add and edit nodes
Example	”Fix this function"	"Pull up the tree from Umtri, then add a node for this feature”

Before You Start: Setting Up an Umtri Account and Getting a Token

To connect MCP, you first need an Umtri account.

1. Sign up and log in to Umtri

Create an account and log in at app.umtri.io.

2. Create a project (Ground)

After logging in, click the “New Ground” button to create a new project. Name it after the project you’re building (for example, bookmark-app).

3. Issue an API token

From the sidebar settings (the gear icon), go to API Tokens, enter a label (for example, claude-code), pick a scope, and hit Generate token. This token is the key that lets Claude Code access Umtri.

There are two scopes:

Scope	What it allows	When to pick it
`read`	Listing grounds, reading the graph and impact, listing bugs and seasons	The default. Safe for any client
`write`	The above, plus creating, updating, and deleting nodes	When you want the AI to edit the tree itself

In this series we’ll have Claude Code write to the tree as well, so choose write.

The token you get starts with umtri_pat_. It’s shown only once and can’t be recovered afterward (only a hash is stored on the server), so copy it somewhere safe right away. If you lose it, revoke it on the same page and issue a new one.

Connecting Umtri’s MCP to Claude Code

Umtri hosts its MCP server itself at https://mcp.umtri.io. So there’s no repo to clone and nothing to install — you just point at that address and authenticate with your token.

Run the following command in your terminal, replacing the token at the end with the one you just issued.

claude mcp add --transport http umtri https://mcp.umtri.io \
  --header "Authorization: Bearer umtri_pat_xxxxxxxxxxxxxxxx"

Running this command registers the Umtri MCP server with Claude Code. Add --scope user to make it available in every project, or --scope local to keep it to the current one.

Verifying the connection

First, check the registration from your terminal.

claude mcp list

If you see umtri: ✓ Connected, you’re good. Typing /mcp inside a Claude Code session also shows you the tools you can actually use.

You can check conversationally too.

Show me my list of Umtri projects

If the connection is working, you’ll see the list of grounds you’ve created in Umtri.

One thing to watch out for — the token isn’t validated when you register it, it’s just stored as-is. So a wrong token still looks like a successful connection, and only the actual calls fail. If no tools show up or calls keep failing, check your token and scope first.

What You Can Do with Umtri’s MCP

Here are the main features Claude Code can use once MCP is connected.

Command	Description
`list_projects`	Look up the list of projects in Umtri
`get_graph`	Retrieve the full tree structure of a specific project
`create_node`	Add a new node (trunk/limb/twig/leaf/vein) to the tree
`update_node`	Edit the name or position of an existing node
`delete_node`	Delete a node
`record_commit`	Log commit information to the Umtri timeline
`create_bug`	Register a bug issue in Umtri
`list_bugs`	Look up the list of registered bugs

Real-World Examples

With MCP connected, you can have conversations with Claude Code like these.

Understanding the current structure

Pull the tree structure for the bookmark-app ground and summarize
what components currently exist

Claude Code reads the tree from Umtri and explains the current structure.

Adding a feature while recording the structure at the same time

Add a search feature to the BookmarkList component.
After that, register the SearchBar component as a leaf node
in the Umtri tree as well.

Writing the code and recording the structure both happen in a single request.

Using the structure to give the AI context

Read the current tree structure from Umtri and suggest where
would be the best place to add a tag filter feature.

The AI grasps the current project structure and offers an opinion from an architectural perspective.

A Word of Caution: Managing Your Token

An API token grants access to your Umtri account. Registering it the way we did above stores it in Claude Code’s own config, so don’t write the token into your project code or into files that get committed, like .mcp.json. It would end up public on GitHub.

If you’d rather keep the token out of config files entirely and handle it as an environment variable, you can run the MCP server locally instead of using the hosted one. The umtri-mcp package runs over stdio and takes the token from the environment.

claude mcp add umtri \
  -e UMTRI_API_TOKEN=umtri_pat_xxxxxxxxxxxxxxxx \
  --transport stdio \
  -- npx -y umtri-mcp

Thanks to npx -y there’s nothing to install up front, and this is also the route you take when you want to pin a version or point at a self-hosted API. For most people, though, the hosted HTTP setup above is simpler.

If you think a token has been exposed, revoke it on the API Tokens page in settings and issue a new one.

What Changes Once MCP Is Connected

Here’s a summary of the difference before and after connecting MCP.

	Before MCP	After MCP
Recording structure	Manually entered into Umtri by hand	Recorded automatically when you ask Claude Code
Understanding the project	Have to open code files directly	One query to the Umtri tree shows everything
Giving the AI context	Explain the structure in every conversation	Load the Umtri tree for instant context

Starting with the next post, we’ll cover what it actually looks like to build features with MCP connected, leaving a trail in the tree as you go.