Skip to content
Jimothydocs

MCP server

The MCP server lets Claude and other AI assistants use Jimothy through the Model Context Protocol. An assistant can see what’s running, start runs and wait for them, approve or reject steps, read logs, and create or change projects, pipelines, triggers, boards and settings. It’s available from 0.6.0.

The server runs inside the app on your computer, so Jimothy must be open for assistants to reach it. It listens on 127.0.0.1 only and needs its own token.

Turn it on

Section titled “Turn it on”
  1. Open Settings → Remote. The MCP server card is below Remote access.
  2. Switch on Let Claude and other AI assistants use Jimothy: start runs, approve steps, build pipelines and projects. The switch applies immediately (no need to click Save).
  3. Pick your client in the row of buttons (Claude Code, Claude Desktop, Codex, OpenCode, Cursor, Devin) and click Copy. The copied setup contains your token; the preview on screen shows it as ••••••••.
  4. Run or paste the setup in your client, as described below.

The card shows Listening on http://127.0.0.1:7719/mcp (this computer only). With remote access on, it also shows the address for other devices on your tailnet; see Use it over Tailscale.

Setting Default Notes
Let Claude and other AI assistants use Jimothy… off Applies immediately.
Port 7719 On 127.0.0.1. Takes effect when you click Save on the Remote tab.

The token is 32 random bytes, stored encrypted in mcp.json in the data folder. It’s separate from the remote access token. Disconnect all clients issues a new one; see Reset the token.

Connect a client

Section titled “Connect a client”

The setup for each client is below, with <token> in place of your token. Copying it from Settings → Remote fills in the token and your port.

Run this in a terminal:

Terminal window
claude mcp add --scope user --transport http jimothy http://127.0.0.1:7719/mcp --header "Authorization: Bearer <token>"

--scope user makes Jimothy available in every project. Check it with claude mcp list.

Other clients

Section titled “Other clients”

Any client that supports MCP over streamable HTTP works. Give it:

  • URL: http://127.0.0.1:7719/mcp
  • Header: Authorization: Bearer <token>

The server only answers POST requests, each with one JSON-RPC message and a JSON reply. It has tools only: no resources, prompts or server-sent event stream.

ChatGPT

Section titled “ChatGPT”

ChatGPT isn’t supported. Its connectors run in OpenAI’s cloud, so they need a public HTTPS URL with OAuth sign-in. Jimothy’s server is only reachable from your computer (and your tailnet), and uses a bearer token.

Example prompts

Section titled “Example prompts”

Once connected, ask in plain language. The assistant reads the overview first and picks the tools it needs.

  • What’s waiting for my approval?
  • Start the Feature pipeline for ENG-42 and tell me when it’s done.
  • Why did run #57 fail? Show me the end of the test step’s log.
  • Approve the plan on run #61 with the comment “keep the migration reversible”.
  • Retry run #57 from the implement step, using Opus this time.
  • Make a pipeline that triages new Linear bugs with Claude and opens a PR.
  • Add a Linear trigger for the ENG team with the label jimothy that runs the Bugfix pipeline.
  • Put these three issues on the Q4 board in order and press play.
  • Which harnesses are installed, and what models does Codex have?

What the tools can do

Section titled “What the tools can do”

The server has 64 tools, covering everything you can do in the app except managing remote access and the MCP server itself. They call the same API as the UI, so they get the same validation, and the app updates live while an assistant works.

Area Tools
Overview get_overview: active runs, approvals waiting, recent runs, unread notifications, and counts. Assistants start here.
Runs list_runs, get_run, get_run_logs, start_run, wait_for_run, approve_step, retry_run, cancel_run, delete_run, edit_run_step, skip_run_step
Projects list_projects, save_project, delete_project, inspect_workspace
Pipelines list_pipelines, get_pipeline, get_pipeline_guide, save_pipeline, duplicate_pipeline, delete_pipeline, list_pipeline_templates, create_pipeline_from_template, export_pipeline, import_pipeline, generate_pipeline
Triggers list_triggers, save_trigger, delete_trigger, test_trigger, poll_trigger, reset_trigger, list_trigger_stages, list_jira_projects
Accounts list_accounts, save_account, delete_account, list_integration_options
Boards list_boards, get_board, save_board, delete_board, set_board_running, add_board_card, move_board_card, board_card_action
Harnesses list_harnesses, get_harness, save_harness, delete_harness, set_harness_enabled, detect_harnesses, set_harness_models
Notifications get_notifications (pass archived for the archived ones), mark_notifications_read, archive_notifications, delete_notifications, list_notification_channels, save_notification_channel, delete_notification_channel, test_notification_channel
Settings get_settings, update_settings

Some details:

  • Starting runs. start_run takes the work as an issue (title, description, and optionally key, URL and labels), because pipeline prompts use {{issue.*}}. Variables passed with it override the pipeline’s {{vars.*}} for that run. wait_for_run returns when the run finishes, stops for approval, or a timeout passes.
  • Approvals. approve_step approves or rejects a waiting step. The comment reaches later steps as {{steps.<id>.comment}}, as it does from the app. For approvals with choices, the assistant passes the picked choices. See Approvals.
  • Writing pipelines. get_pipeline_guide gives the assistant the pipeline format (the same pipeline-builder skill that Build with AI uses), the harnesses and models installed on your machine, and your existing pipelines. The assistant can then write a pipeline itself with save_pipeline, or have one of Jimothy’s harnesses design it with generate_pipeline. Invalid pipelines are refused with the problems listed.
  • Changing things. The save_* tools create an object when it has no id. Otherwise they change only the fields sent: null removes a field, and arrays are replaced, but items with an id (such as steps) keep the fields that weren’t sent. So save_pipeline needs every step, but not every field of every step.
  • Destructive tools. The delete tools, cancel_run and reset_trigger are marked as destructive, so clients that ask before such tools will ask you.

What assistants can read

Section titled “What assistants can read”

Everything a tool returns is redacted before it’s sent:

  • Secrets show as [redacted]: API keys, tokens, passwords, webhook secrets and other fields whose names look like secrets.
  • Environment variable values show as [redacted], whatever their names. That covers the global environment in Settings → General, each project’s Environment and each step’s Environment.
  • Variable names are always visible, so an assistant can see that a step sets GH_TOKEN without seeing its value.

When an assistant sends [redacted] back in a save_* call, Jimothy keeps the stored value. So an assistant can change a project or step without erasing its secrets.

Let assistants read a value

Section titled “Let assistants read a value”

Each row in an environment editor has an eye button between the value and the remove button:

Icon Meaning
Crossed-out eye (default) Hidden from AI assistants (MCP). Assistants see [redacted].
Eye AI assistants (MCP) can read this value.

Click it to switch. The choice is saved with the rest of the form (the Save button in Settings, or the project or pipeline editor). Use it for values an assistant needs to reason about, such as NODE_ENV or a base URL, and leave credentials hidden.

MCP clients can’t change which values are visible. Only you can, in the app. The choice doesn’t affect runs: steps get every value either way.

Security

Section titled “Security”
  • This computer only. The server listens on 127.0.0.1, never on a network interface. Other devices can only reach it through remote access.
  • A token on every request. Requests without Authorization: Bearer <token>, or with the wrong token, get Missing or wrong token. Copy the setup command from Jimothy → Settings → Remote. The token is stored encrypted.
  • No web pages. Requests with an Origin header (anything sent by a browser page) are refused with Requests from web pages are not allowed. MCP clients don’t send one. This also blocks DNS-rebinding attacks.
  • No changes to remote access or the MCP server. update_settings can’t change them, so an assistant can’t open Jimothy to more devices or swap the token.
  • Destructive tools are marked, as described above.

Anyone with the token can do what you can in the app, including starting runs that execute agents on your computer. Treat the copied setup like a password. If it leaks, use Disconnect all clients.

An assistant connected to Jimothy is also an agent that acts for you. What it reads (issue text, run output) can contain instructions meant for it. Keep approval steps before anything that pushes or deploys, and check what the assistant asks to approve. See Data & security.

Use it over Tailscale

Section titled “Use it over Tailscale”

With remote access on, the same endpoint is at /mcp on the remote address, for other computers on your tailnet:

https://<machine>.<tailnet>.ts.net:7443/mcp

It uses the remote access token (the one in the sign-in link, …/pair?t=<token>), not the MCP token. For example, from Claude Code on a laptop on the same tailnet:

Terminal window
claude mcp add --scope user --transport http jimothy https://my-mac.tail1234.ts.net:7443/mcp --header "Authorization: Bearer <remote access token>"

The MCP server must also be switched on; otherwise /mcp answers The MCP server is off. Turn it on in Jimothy → Settings → Remote. In HTTP fallback mode (no HTTPS certificates), the address is http://<machine>:7718/mcp.

Sign out all devices on the Remote access card disconnects these clients too, because it issues a new remote access token.

Troubleshooting

Section titled “Troubleshooting”

Reset the token

Section titled “Reset the token”

Click Disconnect all clients and confirm. Jimothy issues a new token, and every client set up so far stops working (New token issued. Set up your MCP clients again.). Copy the setup again and replace the old entry in each client: remove it first (for example claude mcp remove jimothy, or codex mcp remove jimothy), then add the new one. For Codex, update JIMOTHY_MCP_TOKEN in your shell profile.

Common problems

Section titled “Common problems”
Problem Fix
Port 7719 is already in use. Pick another port. Change Port, click Save, and copy the setup again (it contains the port).
The client can’t connect at all Check that Jimothy is running and the MCP server switch is on. The card should show Listening on….
Missing or wrong token. Copy the setup command from Jimothy → Settings → Remote. The token was reset, or the header is missing. Copy the setup again. For Codex, check that JIMOTHY_MCP_TOKEN is set in the shell that starts Codex.
Not found. The MCP endpoint is /mcp. The URL is missing /mcp.
Requests from web pages are not allowed The request came from a browser page. Use an MCP client instead.
Claude Desktop doesn’t show Jimothy Install Node.js (npx must be on your PATH), check the JSON is valid, and restart Claude Desktop.
Not signed in (over Tailscale) Use the remote access token, not the MCP token. If it was reset, copy the new sign-in link from Settings → Remote.
The MCP server is off… (over Tailscale) Switch on the MCP server on the computer running Jimothy.
The assistant sees [redacted] for a value it needs Click the eye next to the variable in Jimothy and save. See Let assistants read a value.
The card says Manage the MCP server from the desktop app. You’re connected over remote access. Turn the server on and copy the setup from the computer running Jimothy.