Connect Troth to Claude

Troth runs a hosted Model Context Protocol server. Connecting it gives Claude direct access to your specs, tasks, findings, requests, and foundations, so you can plan in a conversation and execute in your terminal against the same project.

You need one string:

https://mcp.troth.dev/mcp

That is the whole server address. There is no API key to paste and no config file to hand-edit for Claude.ai: the first connection opens a browser sign-in, and Claude stores the resulting token for you.

Before you start

Create at least one project first, either by running troth init in a repository (Getting started) or by asking Claude to call create_project once the connector is live. Tools that operate on a project will error until one is selected.

Claude.ai

1. Open Claude.ai and sign in.
2. Open Settings, then Connectors.
3. Choose Add custom connector.
4. For the name, enter Troth.
5. For the URL, enter https://mcp.troth.dev/mcp exactly. No trailing slash.
6. Confirm. Troth now appears in the connector list, disconnected.
7. Choose Connect on the Troth row. A browser window opens for sign-in.
8. Sign in with the same GitHub or Google account you use for the Troth CLI, and approve the authorization.
9. The window closes and the connector shows as connected.

Start a new conversation and check it. Ask Claude to call start_session. If the connector is working, you get back your project’s constitution, foundations, a briefing, and the next ready tasks in one response.

If Claude asks which project to use, say the name. Behind the scenes it calls switch_project, and the choice persists for the rest of the conversation.

Claude Code

Inside a repository that already uses the Troth CLI, prefer the CLI. It runs locally, it is the same code path a human user hits, and it composes with the shell. Add the MCP server when you want the same tools from a Claude Code session that is not sitting in the project directory.

1. In a terminal, run:

   claude mcp add --transport http troth https://mcp.troth.dev/mcp

2. Start Claude Code and run /mcp.

3. Select troth and choose to authenticate. A browser opens.

4. Sign in and approve. Control returns to the terminal.

5. Run /mcp again. The troth entry should read connected.

To remove it later:

claude mcp remove troth

Cursor

1. Open Cursor’s settings and find the MCP servers section.

2. Add a new server, which opens mcp.json for editing. The global file is ~/.cursor/mcp.json; a project-scoped file is .cursor/mcp.json in the repository root.

3. Add the Troth entry:

   {
     "mcpServers": {
       "troth": {
         "url": "https://mcp.troth.dev/mcp"
       }
     }
   }

4. Save the file. Cursor reloads the server list and prompts for sign-in.

5. Approve the authorization in the browser window that opens.

Any other MCP client

Troth speaks streamable HTTP at https://mcp.troth.dev/mcp and authorizes with OAuth 2.1, using dynamic client registration and PKCE. A client that supports remote MCP servers needs no other configuration. Access tokens last one hour and refresh tokens last thirty days; the client handles both refreshes without asking you.

What start_session does

start_session is the tool to call first in any conversation. It composes three other calls into one round trip and returns four things:

Field	What it contains
constitution	The project’s constitution, or Troth’s built-in structural-map constitution if the project has none
foundations	Design bible, design tokens, and design asset paths
briefing	The last decision recorded, current drift, and what changed recently
next_tasks	The top five dependency-ready tasks in priority order

Because it composes them, there is no reason to call get_foundations, get_briefing, and next_tasks separately at the start of a conversation. If one section is unavailable, that section returns an error note and the rest still populate.

The full tool list is in the MCP tool reference.

Checking and fixing a connection

The server has a public health endpoint:

curl https://mcp.troth.dev/health

For anything auth-related, the CLI has a diagnostic that checks token health and connectivity:

troth mcp check

CLI authentication and MCP authentication are deliberately separate. troth login authenticates you, a developer on your own machine, and stores an encrypted token locally. The MCP connector authenticates a remote Claude session against the hosted server. Logging out of one does not log out the other.

Message	What it means	What to do
Session expired	The one-hour access token ran out	Reconnect the connector in your client’s settings
Token revoked	The token was explicitly revoked	Re-authorize the Troth connector
Token not recognized	The token is invalid or corrupted	Remove the connector and add it again
Authorization failed	A generic auth failure	Run troth mcp check for diagnostics

If tools return an error about no project being selected, ask Claude to call list_projects and then switch_project with the name you want.