# Exponential MCP

[![npm version](https://img.shields.io/npm/v/exponential-mcp.svg)](https://www.npmjs.com/package/exponential-mcp)

Connect Claude to your [Exponential](https://exponential.im) workspace. Manage projects, actions, and OKRs directly from Claude.

## Quick Start

### 1. Create an Agent

Open [exponential.im/settings/agents/new](https://www.exponential.im/settings/agents/new):
- Name the agent after the app it will run in (for example "Claude")
- Pick the workspaces it may work in
- Click **Create agent** and copy the key (`exp_agent_…`) — it is shown once

The agent is its own identity: what Claude does in Exponential is attributed to it, not to you.

### 2. Set Up the MCP Server

```bash
npx exponential-mcp init
```

Paste the agent key when prompted.

### 3. Configure for Your Claude Client

**For Claude Desktop:**
- `exponential-mcp init` will automatically configure Claude Desktop
- Restart Claude Desktop

**For Claude Code (VSCode Extension):**
- The server uses `.mcp.json` in your project directory
- Reload your VSCode window (`Cmd+Shift+P` → "Developer: Reload Window")
- The server will be available in your current project

### 4. Ask Claude to manage your tasks!

## One Key per App

`init` saves one key that every app on the machine shares. To give each app its own identity, create a separate agent per app and set its key in that app's MCP config. `EXPONENTIAL_API_KEY` overrides the key saved by `init`.

**Claude Code:**

```bash
claude mcp add exponential -e EXPONENTIAL_API_KEY=<key> -- npx -y exponential-mcp serve
```

**Codex** (`~/.codex/config.toml`):

```toml
[mcp_servers.exponential]
command = "npx"
args = ["-y", "exponential-mcp", "serve"]
env = { EXPONENTIAL_API_KEY = "<key>" }
```

**Claude Desktop or `.mcp.json`:** add `"env": { "EXPONENTIAL_API_KEY": "<key>" }` to the `exponential` entry.

Restart the app afterwards. Re-running `init` rewrites Claude Desktop's entry, including its `env`.

## What Claude Can Do

Once connected, Claude can:

- **List projects** – "What projects am I working on?"
- **View actions** – "Show my active tasks"
- **Create actions** – "Add a task to call John tomorrow"
- **Complete actions** – "Mark the report task as done"
- **View OKRs** – "What are my Q1 goals?"
- **Search** – "Find anything related to Kenya"
- **Work the CRM** – "Log that I emailed Keily today" / "Move the Onionpress deal to Proposal"
- **Run the product backlog** – tickets, features, epics, stories, pages and decisions
- **Track time** – log, confirm and report on the day

## Manual Setup

### For Claude Desktop

**macOS (recommended path):** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Legacy path:** `~/.claude/claude_desktop_config.json`

Add this to the appropriate file:

```json
{
  "mcpServers": {
    "exponential": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/exponential-mcp/dist/index.js"]
    }
  }
}
```

### For Claude Code (VSCode Extension)

Create a `.mcp.json` file in your project directory:

```json
{
  "mcpServers": {
    "exponential": {
      "command": "npx",
      "args": ["-y", "exponential-mcp", "serve"]
    }
  }
}
```

Then reload your VSCode window.

**Note:** The key is stored in the Exponential SDK config store (created by `npx exponential-mcp init`), so you don't need to specify it in the MCP configuration unless the app needs its own key (see [One Key per App](#one-key-per-app)). A personal JWT token from [Settings → API keys](https://www.exponential.im/settings/api-keys) also works, but then Claude acts as you. Run `exponential-mcp config` to see the current storage path and values. Run `exponential-mcp doctor` to print a recommended MCP config snippet for your machine.

## Commands

```bash
# Initialize with an agent key
exponential-mcp init

# Show current config
exponential-mcp config

# Diagnose local setup
exponential-mcp doctor

# Start server manually (usually not needed)
exponential-mcp serve
```

## Available Tools

| Tool | Description |
|------|-------------|
| `get_workspaces` | List all workspaces |
| `get_projects` | List projects (optionally by workspace) |
| `get_project` | One project in full: linked objectives & key results, DRI, team, dates |
| `update_project` | Rename, change status/priority, set dates, re-link to OKRs |
| `get_actions` | List actions/tasks (filter by project or status; no date filtering) |
| `get_todays_actions` | **What's on your plate now** — overdue / today / inbox, across all workspaces |
| `get_overdue_triage` | Why the overdue pile is that size: bulk-created cohorts vs real debt |
| `create_action` | Create a new task (supports natural language) |
| `update_action` | Rename, re-prioritise, move project, or set dates (incl. `scheduledStart`) |
| `defer_actions` | Amnesty: clear dates, back to the project backlog untimed |
| `reschedule_actions` | Move actions to a new do-date |
| `complete_action` | Mark an action as done |
| `get_goals` | List objectives, flat or as the annual → quarterly tree |
| `get_key_results` | List key results, grouped by objective or flat |
| `get_meetings` | List meetings, newest first, with a summary preview (no notes/transcript) |
| `get_meeting` | One meeting with notes; transcript on request |
| `create_meeting` | Record a meeting from a transcript or notes |
| `update_meeting` | Edit title, description, summary, date, or replace notes |
| `append_meeting_notes` | Add to a meeting's notes without overwriting them |
| `search` | Search across everything |

### Domain tools

Alongside the tools above, every part of the [Exponential SDK](https://www.npmjs.com/package/exponential-sdk)
is exposed as one tool per domain, so the MCP server can do anything the SDK
and CLI can:

`actions` · `projects` · `workspaces` · `positions` · `goals` · `key_results` · `meetings` ·
`time` · `decisions` · `contacts` · `organizations` · `deals` · `products` ·
`features` · `scopes` · `requirements` · `areas` · `stories` · `epics` ·
`tickets` · `labels` · `pages` · `databases` · `comments`

Each takes `{ operation, params }`. The tool description lists every operation
with a one-line signature; `operation: "describe"` returns the full parameter
schema for one operation (`params: { operation: "create" }`) or all of them.
Invalid params come back as an error that includes the expected schema.

```json
{ "operation": "add_interaction",
  "params": { "contactId": "…", "type": "EMAIL", "direction": "OUTBOUND", "subject": "Intro" } }
```

`comments` covers comments on actions, features, pages, goals and tickets — pass
`target` to choose which.

`positions` is a workspace's roles & responsibilities — the Positions on the
settings page: list, create, update, set_holders, delete, and import_many
(upsert by title, with a dry run). Writes need your own API key, not an agent
key, and owner/admin, except that a holder may edit their own Position's remit.

`databases` is the typed write path for tables inside pages (ADR-0078): a
database is a block in a page body and each row is a page. **Values are typed
per property** — a select takes an option name, a date an ISO string, a person
a user ID — and a wrong value is refused naming the property, so call `get`
first to learn the schema. Reading the page with `pages` shows the table.

### Asking about the day

Use **`get_todays_actions`**, not `get_actions`, for anything about today,
priorities, or what the user is behind on. `get_actions` has no date filtering
at all, so it cannot distinguish overdue work from anything else.

When there is a lot of overdue work, follow up with **`get_overdue_triage`**
before proposing what to do. A large overdue count is usually a few bulk writes
— a generated project plan stamped every row with one timestamp — not a large
number of missed commitments. Those are **cohorts**, and the honest disposition
is `defer_actions` (amnesty); `reschedule_actions` would just re-inflict the
same pile tomorrow. Individually-dated **loose** actions are the ones that
deserve a real decision.

## Development

```bash
# Clone the repo
git clone https://github.com/your-org/exponential-mcp
cd exponential-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

## License

MIT