---
title: "Local MCP server"
description: "Run @myspec/mcp-server over stdio in Claude Desktop, Claude Code, Cursor and other local MCP clients."
---

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

# Local MCP server

The local MySpec MCP server is the `@myspec/mcp-server` npm package. Your MCP
client starts it on your machine and talks to it over stdio. Besides the tools
the [remote server](/mcp/remote-server/) offers, it can save spec files to disk,
upload attachments straight from a file path, and share a local folder with
Brownfield sessions.

**Requirements:** Node.js 22 or later.

## Install

1. **Sign in**

   ```sh
   npx @myspec/mcp-server login
   yarn dlx @myspec/mcp-server login
   pnpm dlx @myspec/mcp-server login
   bunx @myspec/mcp-server login
   ```

   Your browser opens. Sign in to MySpec and approve the request. If you belong
   to more than one organization, the CLI asks which one to use.
2. **Add the server to your client**

   ### Claude Code

   ```bash
   claude mcp add myspec --scope user -- npx -y @myspec/mcp-server
   ```

   ### Claude Desktop

   Add this to `claude_desktop_config.json`, then restart Claude Desktop:

   ```json title="claude_desktop_config.json"
   {
     "mcpServers": {
       "myspec": {
         "command": "npx",
         "args": ["-y", "@myspec/mcp-server"]
       }
     }
   }
   ```

   ### Cursor and others

   Most clients read the same JSON shape, for example `.cursor/mcp.json` or
   a project `.mcp.json`:

   ```json title=".mcp.json"
   {
     "mcpServers": {
       "myspec": {
         "command": "npx",
         "args": ["-y", "@myspec/mcp-server"]
       }
     }
   }
   ```
3. **Check it works**

   Ask your agent to "list my MySpec projects".

You can add the server before you sign in. Until you do, each tool call returns
an error that tells you to run `login`; once you sign in, tools work without
restarting the client.

## Sign in

```text
npx -y @myspec/mcp-server login               Sign in with your browser
npx -y @myspec/mcp-server login --paste       Sign in from another device
npx -y @myspec/mcp-server login --org <slug>  Sign in and choose the organization
npx -y @myspec/mcp-server auth status         Show who you are signed in as
npx -y @myspec/mcp-server logout              Sign out and remove saved credentials
```

When installed globally, the command is also available as `myspec-mcp`.

### Choose the organization

Every MySpec sign-in works in one **active organization**. `login` picks it for
you when you belong to one organization and asks when you belong to several.
Pass `--org` to choose without a prompt, which you need in a non-interactive
shell, or to switch organization later:

```bash
npx -y @myspec/mcp-server login --org my-team
```

### Sign in from another device

When the browser is on a different machine than the CLI (a remote dev box, a
container), use `--paste`:

```bash
npx -y @myspec/mcp-server login --paste
```

Open the printed link in any browser and sign in. If the page cannot reach the
CLI, it shows a value like `<code>.<state>`. Copy **the whole value, including
the dot**, and paste it into the terminal straight away: it expires a minute
after you finish signing in.

> **Only open the sign-in link on a machine you trust**
>
> The sign-in page hands a one-time code to a program listening on that
> machine. Anything else running there could take the code and act as you
> until you sign out.

### Check your sign-in

```bash
npx -y @myspec/mcp-server auth status
```

```text
Signed in to https://auth.myspec.dev
  Account:       jane@example.com
  Organization:  Acme Inc (acme)
  Credential:    login session (/home/jane/.myspec/oauth_creds.json)
```

It exits with `0` when you are signed in and `2` when you are not, so
`auth status || auth login` works in scripts.

## Use an API token instead

For anything that starts without a person present (a server, a container, CI),
use an [API token](/mcp/api-tokens/) instead of `login`. Put it in the client's
`env` block:

```json title=".mcp.json"
{
  "mcpServers": {
    "myspec": {
      "command": "npx",
      "args": ["-y", "@myspec/mcp-server"],
      "env": { "MYSPEC_API_TOKEN": "msp_pat_…" }
    }
  }
}
```

or register it in one command:

```bash
claude mcp add --scope user myspec \
  --env MYSPEC_API_TOKEN=msp_pat_… \
  -- npx -y @myspec/mcp-server
```

The token is never written to disk. See [API tokens](/mcp/api-tokens/#use-a-token-with-the-local-server)
for the file-based option and how credentials take precedence.

## Share a local folder for Brownfield projects

Brownfield sessions read your existing code. The `reverse` command lets
MySpec's AI read **one folder** on your machine, and nothing outside it:

```bash
npx -y @myspec/mcp-server reverse --root /path/to/your/project
```

- Start it **before** you start the Brownfield session, and keep it running for
  the whole session.
- Run it with the same MySpec account you use in the browser.
- Only one bridge runs per account.

> **Choose the folder carefully**
>
> Common secret files are excluded by default, but the AI can read anything
> else under `--root`. Point it at your project folder, never at your home
> directory, and keep credentials out of that folder.

## Environment variables

| Variable | Purpose |
|---|---|
| `MYSPEC_API_TOKEN` | An [API token](/mcp/api-tokens/) (`msp_pat_…`) for unattended use. Never written to disk. Needs version 0.3.0 or later. |
| `MYSPEC_USER_AUTH_URL` | The MySpec sign-in server. Defaults to `https://auth.myspec.dev`; you normally never set it. |
| `MYSPEC_DOWNLOAD_ROOT` | Folder used to cache files read with `read_spec_file`. Defaults to `~/.myspec`. |

## Files on your machine

The server keeps its state in `~/.myspec/`:

- `settings.json`: non-secret settings, such as which sign-in server you use.
- `oauth_creds.json`: your sign-in, readable only by you (mode `0600`).

`logout` deletes `oauth_creds.json`. `download_spec_file` saves files under a
`.specs/` folder in the working directory by default, so downloads don't mix
with your repository's own files.

## Edit spec files safely

Several people and AI sessions can work on a project at once. `get_spec_file`
and `read_spec_file` return a `content_version`. Pass it to `update_spec_file`
as `expected_version`: if someone else saved in the meantime, the update is
rejected instead of overwriting their work. Read the file again, combine the
changes, then update.

## Troubleshooting

| Problem | What to do |
|---|---|
| Tools say you are not signed in | Run `npx -y @myspec/mcp-server login`, or check `auth status`. |
| `Pasted token is missing a state suffix` | Copy the whole `<code>.<state>` value, including the dot, not just the code. |
| `OAuth code exchange failed: HTTP 401` after pasting | The code expired. Run `login --paste` again and paste the value as soon as it appears. |
| `MYSPEC_API_TOKEN` seems ignored | Update the package: the variable needs version 0.3.0 or later. `npx -y` always fetches the latest. |
| Brownfield session cannot see your code | Make sure `reverse` is running with the same account as your browser, and that `--root` points at the project folder. |

Source: https://docs.myspec.dev/mcp/local-server/index.mdx