> ## 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. # MCP server > Wire Runwita into Claude Code, Claude Desktop, or Cowork. Push engagements, look up contacts, query journeys from outside the app. 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](https://nodejs.org) or `brew install node`. 4. **An MCP client.** One of: * [Claude Code](https://claude.com/product/claude-code) (the CLI) * [Claude Desktop](https://claude.ai/download) (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. ```json theme={null} { "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: ```json theme={null} { "...": "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: ```bash theme={null} 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. ### Copy instead of symlink (if you prefer) If you'd rather not have a live link into `/Applications`: ```bash theme={null} 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: | Tool | Purpose | | ------------------ | ----------------------------------------------------------------------------------------------- | | `list-journeys` | All journeys with engagement and action counts. | | `match-journey` | Fuzzy customer-name lookup. | | `create-journey` | New journey with customer, use case, dates, owner. | | `list-engagements` | All engagements for a journey. | | `push-engagement` | Push structured meeting or email data (the big one, supports `type: "email"` with `emailMeta`). | | `list-topics` | All topics for a journey with touchpoint counts. | | `list-contacts` | All people with company, role, journey/engagement counts. | | `get-contact` | Full contact detail + their journeys / engagements / actions. | | `search-contacts` | Search by name / company / role. | | `update-contact` | Update 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: ```bash theme={null} 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: ```bash theme={null} 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: ```bash theme={null} (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: ```bash theme={null} # 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 The shape `push-engagement` expects. How topic matching behaves when an MCP-pushed engagement lands.