Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runwita.com/llms.txt

Use this file to discover all available pages before exploring further.

Runwita ships with a built-in MCP (Model Context Protocol) server and a companion skill file. Once wired up, you can ask Claude to push meeting notes, find customers, list open topics, or update contacts, and it all lands in the same SQLite database your Runwita app reads from. No separate install needed. Both files are bundled inside the Runwita dmg. This is a power-user feature. If you’ve never heard of MCP, you can skip this page and use Runwita normally. Nothing here changes how the app works.

​
Two things to wire up

Setup has two independent pieces. You want both, but they serve different purposes:
  1. MCP server, makes the tools available. Required for every client. Without this, nothing happens.
  2. Skill file, teaches Claude when to use the tools (e.g. “save this meeting to runwita” triggers the skill, Claude knows to call push-engagement). Recommended for Claude Code and Cowork. Claude Desktop doesn’t use skills.
If you skip the skill install, the tools still work, you’ll just have to tell Claude explicitly which tool to call. The skill makes natural phrasing (“push this to runwita”) just work.

​
Prerequisites

  1. Runwita 1.0.0 or later installed at /Applications/Runwita.app.
  2. Opened Runwita at least once. The first launch creates ~/Library/Application Support/Runwita/app.db. The MCP server will error out if the DB doesn’t exist yet.
  3. Node 18+ somewhere on your PATH. If you’re not sure, run node --version in Terminal. If it errors, install from nodejs.org or brew install node.
  4. An MCP client. One of:
    • Claude Code (the CLI)
    • Claude Desktop (the Mac app)
    • Cowork (Claude’s workspace app, if you have access)
    • Any other MCP client that speaks stdio

​
Step 1, MCP server (all clients)

Exactly the same snippet works for every client, only the file you paste it into changes. 
{
  "mcpServers": {
    "runwita": {
      "command": "node",
      "args": [
        "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/runwita-mcp-server.js"
      ]
    }
  }
}
That path is stable, it’s the same on every Mac where Runwita is installed in /Applications. No substitution required.

​
Claude Code

Edit ~/.claude.json. If the file has an existing "mcpServers" key, add "runwita" inside it: 
{
  "...": "other config",
  "mcpServers": {
    "...": "other servers",
    "runwita": {
      "command": "node",
      "args": [
        "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/runwita-mcp-server.js"
      ]
    }
  }
}
If the file doesn’t have "mcpServers" yet, add the whole block. Restart Claude Code. Verify by running: 
/mcp
You should see runwita listed. Expand it and you should see 10 tools (list-journeys, push-engagement, list-topics, etc.).

​
Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json. Same shape as above, add a runwita entry under mcpServers. Fully quit and reopen Claude Desktop (⌘Q, then relaunch). A small hammer icon in the input bar shows the MCP tools are loaded.

​
Cowork

Cowork reads MCP config from its own UI. Go to Settings → MCP servers → Add server and paste:
  • Name: runwita
  • Command: node
  • Args: /Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/runwita-mcp-server.js
Save. Cowork restarts the connection automatically.

​
Step 2, skill install (Claude Code + Cowork)

Skip this section if you only use Claude Desktop. Claude Code and Cowork both read skill files from ~/.claude/skills/. Each skill lives in its own directory containing a SKILL.md with YAML frontmatter. The Runwita skill is bundled at: 
/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/RUNWITA-MCP-GUIDE.md
Symlink it into the skills directory so it activates automatically and stays fresh on upgrades: 
mkdir -p ~/.claude/skills/runwita
ln -sf "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/RUNWITA-MCP-GUIDE.md" \
  ~/.claude/skills/runwita/SKILL.md
Because it’s a symlink, every time you install a new Runwita dmg the skill auto-updates, no re-linking needed. After symlinking, the skill activates whenever you say things like:
  • “push this to runwita”
  • “save my meeting in runwita”
  • “add this to the Acme journey”
  • “what topics are open on runwita?”
Claude Code picks it up on its next invocation; no restart required. For Cowork, the skill loader reads on app launch, fully quit (⌘Q) and reopen to pick up changes. If you’d rather not have a live link into /Applications: 
mkdir -p ~/.claude/skills/runwita
cp "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/RUNWITA-MCP-GUIDE.md" \
  ~/.claude/skills/runwita/SKILL.md
Tradeoff: you’ll need to re-run this command after every Runwita dmg upgrade to pick up skill changes.

​
Your first push, the minimum workflow

Once the server is wired up, here’s the shortest path to something useful. Copy a meeting transcript to your clipboard first, then in your MCP client:
Push this meeting into Runwita under customer “Maplewood Inn”: [paste transcript]
The LLM will:
  1. Call match-journey with "Maplewood Inn" to find the journey ID (or create-journey if it doesn’t exist).
  2. Call list-topics on that journey to see what topics already exist.
  3. Extract structured data from the transcript, sections, decisions, actions, attendees, topics.
  4. Call push-engagement with all of that, mapping new topics to existing ones where it makes sense.
When it’s done, switch to Runwita and open that journey’s timeline. The engagement shows up immediately.

​
Using the individual tools

You don’t have to push a whole meeting. Each tool is callable on its own. A few useful patterns: “What journeys do I have?” → calls list-journeys, returns customer, use case, engagement count, open actions. “Who’s on the Maplewood Inn journey?” → calls match-journey then list-engagements to get people. “Find contacts at Acme Corp” → calls search-contacts with the query. “Update Jane Doe’s role to ‘Head of Design’” → calls search-contacts then update-contact.

​
Tool reference

The server exposes 10 tools. Full schemas live inside runwita-mcp-server.js but here’s the shape:
ToolPurpose
list-journeysAll journeys with engagement and action counts.
match-journeyFuzzy customer-name lookup.
create-journeyNew journey with customer, use case, dates, owner.
list-engagementsAll engagements for a journey.
push-engagementPush structured meeting or email data (the big one, supports type: "email" with emailMeta).
list-topicsAll topics for a journey with touchpoint counts.
list-contactsAll people with company, role, journey/engagement counts.
get-contactFull contact detail + their journeys / engagements / actions.
search-contactsSearch by name / company / role.
update-contactUpdate name, role, or company.

​
Important: the rules Claude has to follow

These are enforced by the skill file (RUNWITA-MCP-GUIDE.md) but worth knowing so you can spot bad behaviour:
  • Always match-journey before create-journey, otherwise duplicates pile up.
  • Always list-topics before push-engagement, so Claude can reuse existing topics instead of making near-duplicates.
  • Never push two engagements to the same journey in parallel, the SQLite connection can race, and the Intelligence layer’s stale flags get out of sync.
  • Every action must have a due_date, no exceptions. Actions without deadlines never get chased and clutter the open-actions list forever.
  • Pass ticktick_id on actions if you created the TickTick task yourself, the app honours existing links and won’t create a duplicate.

​
Gotchas

1. TickTick sync doesn’t happen from the MCP path. When you push an engagement via MCP, actions are saved but not auto-created in TickTick. The MCP server is intentionally thin, it doesn’t load Runwita’s settings or hit external APIs. If you want TickTick tasks from MCP-pushed engagements, either:
  • Create the TickTick tasks yourself first and pass ticktick_id on each action, or
  • Create the engagement via Runwita’s in-app Inbox flow, which does sync automatically.
2. Intelligence layer goes stale but doesn’t auto-refresh. Same reason, the MCP server doesn’t have an LLM client. After an MCP push, open Runwita’s Intelligence tab and you’ll see amber Stale badges. Click Re-analyze on each card, or just push the next engagement via the in-app flow and the background refresh will clear them. 3. Schema version mismatch. If you ever mix MCP server versions (e.g. keep an older Runwita.app installed while using a newer MCP server from a separate clone), the DB schema can drift. Don’t do that. Always run the MCP server that came with your installed Runwita. 4. Node has to be on PATH. MCP clients spawn node via the shell. If node --version works for you in Terminal but the MCP client can’t find it, you probably have node installed via nvm in a shell init script that MCP clients don’t source. Fix: install node globally via brew install node or symlink /usr/local/bin/node to your nvm-managed binary. 5. The DB file must exist before the server starts. If you wipe ~/Library/Application Support/Runwita/app.db (or have never launched Runwita), the MCP server crashes on first tool call. Just launch Runwita once, it creates the DB automatically.

​
Troubleshooting

“Claude Code says no tools are available”
  • Run /mcp and check whether runwita is listed.
  • If not, check ~/.claude.json is valid JSON (jq . ~/.claude.json, errors mean bad syntax).
  • If it’s listed but shows 0 tools, the server crashed on startup. Try running the server manually to see the error: 
    node /Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/runwita-mcp-server.js
    It should hang waiting for stdin. If instead it prints an error and exits, the error will tell you what’s wrong.
“push-engagement returns empty or fails silently” Usually means the journeyId you passed doesn’t exist. Run list-journeys first to get real IDs. “I pushed an engagement but Runwita doesn’t show it”
  • Make sure Runwita was restarted (or its current view is refreshed), the in-app journey list doesn’t auto-poll the DB.
  • Check the right journey, match-journey does fuzzy matching, so "Acme" might match "Acme Corp" and vice versa. list-journeys confirms.
“Two engagements showed up for one meeting” You called push-engagement twice, or two MCP clients pushed concurrently. Delete one in the app (swipe on the timeline dot, then Delete). “Saying ‘runwita’ doesn’t trigger anything” The skill file isn’t installed (or isn’t where Claude Code / Cowork is looking). Check the symlink exists: 
ls -la ~/.claude/skills/runwita/SKILL.md
Should show a symlink pointing into /Applications/Runwita.app/.... If it’s missing, re-run the ln -sf command from Step 2. If it’s there but the trigger still doesn’t fire, restart the client (⌘Q + reopen for Cowork / Claude Desktop; Claude Code picks it up on next prompt).

​
Verify the server runs on your Mac

Run this in Terminal, it fires a tools/list request and should print a JSON blob listing all 10 tools: 
(echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'; sleep 1) \
  | node "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/runwita-mcp-server.js"
If that works, the bundled server is fine and any failure is on the MCP client side, config syntax, restart, or PATH.

​
Reading the bundled files directly

If you want to inspect the canonical setup guide or the skill prompt that ships with your installed Runwita, both live inside the app bundle: 
# The full setup guide
open "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/docs/MCP-GUIDE.md"

# The skill file (the prompt Claude Code / Cowork loads)
open "/Applications/Runwita.app/Contents/Resources/app.asar.unpacked/src/mcp/RUNWITA-MCP-GUIDE.md"
The bundled copies are the source of truth, they ship with each release. Useful if you want to see exactly what rules the LLM is being told to follow on your machine.

​
What’s next

Engagements

The shape push-engagement expects.

Topics

How topic matching behaves when an MCP-pushed engagement lands.