> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsolve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Upsolve Local from Claude and Codex

> Add Upsolve Local's MCP server to Claude Code, Claude Desktop or Codex with one command, to build workspaces or to ask them questions, with nothing to sign in to.

Upsolve Local comes with the same two MCP servers as Upsolve Cloud, with the same tools. Your assistant starts the server itself, on your Mac, with one command. There is no URL to enter, no key and no sign-in.

## Before you start

Upsolve Local has to be running:

```bash theme={null}
npx @upsolve-labs/analytics
```

Leave it running. The assistant finds it by itself. If it is stopped, or you start it after the assistant, nothing needs to be reconnected: see [How it connects](#how-it-connects).

## The builder server or the user server

| | `mcp` | `mcp --user` |
| - | - | - |
| **For** | Building | Asking questions |
| **Tools** | Create, edit, test and publish workspaces, plus every tool the user server has | Ask a workspace's agent, and keep your own threads, favorites and canvases |
| **Answers from** | The draft or any version you choose, as any project user you choose, and the published version as yourself | The published version only, as yourself |
| **Can change a workspace** | Yes | No |
| **Same as the cloud connector** | Upsolve (`/mcp`) | Upsolve Analytics (`/user`) |

Upsolve Local has one person and no sign-in, so both servers act as you. What `--user` changes is **how** you are seen. With `--user` the assistant gets only the analytics tools, and uses them the way an end user of your workspace would:

* **As your own project user.** Upsolve gives you a project user of your own in each project, and every `--user` call runs as that user, never as one you pick.
* **Against each workspace's published production version.** A draft is never answered from. Publish your changes and promote the version to production before you ask, either in the app or with the builder server.
* **With your own history.** The threads, favorites and canvases it reads and saves are your own, the same ones the Upsolve Local app shows you.

Pick `--user` to hand your assistant a read-and-analyze surface that cannot change any workspace. Pick `mcp` to build. You can add both, side by side.

## Add it to your assistant

### Claude Code

```bash theme={null}
claude mcp add upsolve -- npx -y @upsolve-labs/analytics mcp
claude mcp add upsolve-analytics -- npx -y @upsolve-labs/analytics mcp --user
```

The first line adds the builder server, the second the user server. Run either one, or both.

### Claude Desktop

Open **Settings → Developer → Edit Config**, which opens `~/Library/Application Support/Claude/claude_desktop_config.json`, and add the servers you want under `mcpServers`:

```json theme={null}
{
  "mcpServers": {
    "upsolve": {
      "command": "npx",
      "args": ["-y", "@upsolve-labs/analytics", "mcp"]
    },
    "upsolve-analytics": {
      "command": "npx",
      "args": ["-y", "@upsolve-labs/analytics", "mcp", "--user"]
    }
  }
}
```

Then quit Claude Desktop completely (`⌘Q`, not just closing the window) and open it again.

Claude Desktop does not read your terminal's `PATH`. If it reports that the server failed to start, put the full path that `which npx` prints in `command` (for example `/opt/homebrew/bin/npx`), and add `"env": { "PATH": "<folder of node>:/usr/bin:/bin" }` to the server, with the folder that `which node` prints.

### Codex

```bash theme={null}
codex mcp add upsolve -- npx -y @upsolve-labs/analytics mcp
codex mcp add upsolve-analytics -- npx -y @upsolve-labs/analytics mcp --user
```

Or add them to `~/.codex/config.toml` yourself:

```toml theme={null}
[mcp_servers.upsolve]
command = "npx"
args = ["-y", "@upsolve-labs/analytics", "mcp"]

[mcp_servers.upsolve-analytics]
command = "npx"
args = ["-y", "@upsolve-labs/analytics", "mcp", "--user"]
```

### Try it

Ask your assistant something like "Which workspaces do I have in Upsolve?". It starts by looking up your organization and project, as it does with Upsolve Cloud, and goes on from there.

## How it connects

* **There is nothing to configure.** Each time a tool is called, the server finds Upsolve Local on your Mac, asks it for a session that lasts one hour, and renews it before it runs out.
* **Upsolve Local can stop and start.** While it is stopped, every tool answers `Upsolve Local is not running. Start it with: npx @upsolve-labs/analytics — then ask again.` Start it and ask again: the assistant does not need restarting, even when Upsolve comes back on another port.
* **Update both together.** The server is part of the Upsolve Local release `npx` runs. After you update Upsolve Local, restart your assistant too, so both run the same release.

## What is different from the cloud

* **Charts arrive as JSON.** In Upsolve Cloud a chart the agent draws appears in the conversation. Upsolve Local has no interactive chart yet: the chart's data and settings come back as JSON in the tool's answer, which the assistant can read, summarize or draw itself.
* **The app's limits apply.** The tools are the cloud's, and they reach the same Upsolve Local the app does, so what [Upsolve Local does not have](/local/quickstart#what-is-in-upsolve-local-and-what-is-not) is not available through them either.

If something does not work, [Troubleshooting](/local/troubleshooting#using-upsolve-from-an-assistant-mcp) has every message the server can give. `npx @upsolve-labs/analytics mcp --help` lists its options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.