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 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

npx @myspec/mcp-server login

yarn dlx @myspec/mcp-server login

pnpm dlx @myspec/mcp-server login

bunx @myspec/mcp-server login

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

{
  "mcpServers": {
    "myspec": {
      "command": "npx",
      "args": ["-y", "@myspec/mcp-server"]
    }
  }
}

{
  "mcpServers": {
    "myspec": {
      "command": "npx",
      "args": ["-y", "@myspec/mcp-server"]
    }
  }
}

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

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:

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:

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.

Check your sign-in

npx -y @myspec/mcp-server auth status

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 instead of login. Put it in the client’s env block:

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

or register it in one command:

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 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:

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.

Environment variables

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