Skip to main content
Back to Homepage

MCP Server

@myspec/mcp-server — your specs, in your AI Coding Agent

A Model Context Protocol server that exposes your MySpec projects, spec files, and attachments to Claude Desktop, Claude Code, and Cursor — over stdio, authenticated with OAuth. It can also run in reverse, exposing your local files to the cloud AI agent.

Install with npx. No separate CLI to learn.

Two ways to connect

MCP server (default)

Your AI editor is the MCP client; @myspec/mcp-server is the MCP server. Your editor calls tools to read and write MySpec projects, spec files, and attachments.

Reverse (opt-in)

Run @myspec/mcp-server reverse --root <dir> and the roles flip: the MySpec cloud agent becomes the MCP client, and your machine becomes the server, exposing a read-only view of one local directory so the agent can factor your existing codebase into a spec.

Install & sign in

Run the server directly with npx — nothing to install globally.

$ npx -y @myspec/mcp-server login # browser-based OAuth sign-in

You can add the server to your AI client before signing in — it will start and connect, and each tool call will prompt you to run login. Once you sign in, tools work immediately without restarting your client.

Configure your client

Add MySpec to your .mcp.json (Claude Code, Cursor) or equivalent MCP client config: 

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

Platform tools

Once signed in, your AI editor gets direct, read/write access to MySpec projects and spec files — no copy-pasting from the browser.

Projects

  • list_projects
  • get_project
  • create_project
  • update_project
  • archive_project / ...

Spec files

  • list_spec_file / get_spec_file
  • read_spec_file
  • upload_spec_file
  • update_spec_file / ...

Attachments

  • get_attachment
  • upload_attachment

PDF, DOCX, XLSX, and UTF-8 text files up to 10 MB.

Spec file writes are saved as new revisions, and deleted files go to a recoverable Trash Bin first — nothing is destroyed by accident.

Local file access (read-only)

Want the cloud AI agent to see your local codebase while it drafts a spec? The @myspec/mcp-server reverse command connects out to MySpec and exposes a read-only view of a single directory you choose:

$ npx @myspec/mcp-server reverse --root ./my-project
  • local_fs_list_dir — list directory entries under the granted root
  • local_fs_read_file — read a file under the granted root
  • local_fs_grep — search for a pattern under the granted root
  • local_pack_codebase / local_pack_codebase_read_page — pack the codebase into a paginated text bundle for the agent to read

Every path is sandboxed to the directory you pass with --root, and secret files (SSH keys, .env-style credentials, etc.) are always excluded — this is read-only exposure, not a sync engine.

Authentication

The server authenticates with OAuth access and refresh tokens, not a long-lived API key. login opens a browser (or use login --paste if a browser isn't available); credentials are stored locally under ~/.myspec/ with restricted file permissions. Access tokens refresh automatically in the background — logout revokes them.

Environment variables

  • MYSPEC_REFRESH_TOKEN — seed credentials without running login interactively
  • MYSPEC_DOWNLOAD_ROOT — where downloaded spec-file content is cached on disk

Frequently asked questions

What can I do with the MySpec MCP server?

Once it's connected to Claude Desktop, Claude Code, or Cursor, your AI editor can list and manage your MySpec projects, and read, create, and update spec files and attachments directly — no switching to the browser to copy content back and forth.

Can I upload existing local spec files into a MySpec project?

Yes. Point your AI editor at a local file and ask it to upload it — the upload_spec_file tool accepts a local file path directly, so a requirements.md or solution.md already sitting in your repo can be brought into a MySpec project without copy-pasting. Use update_spec_file the same way to overwrite an existing file with a new revision.

Can it see my local codebase, not just spec files?

Yes, if you opt in. Running npx @myspec/mcp-server reverse --root ./my-project exposes a read-only view of that directory to the cloud AI agent, so it can list files, read them, grep across them, or pack the whole codebase into a bundle for context — useful when drafting a spec for a brownfield project.

Do I need to install a separate CLI first?

No. npx -y @myspec/mcp-server runs the server directly — there's nothing to install globally, and no other CLI is required.

Does the MCP server replace app.myspec.dev?

No. The MCP server gives your AI editor access to specs that already exist — it doesn't run the Architect Interview or Vibe Specify'ing. To create a new spec bundle or drive our Spec-Driven AI workflows, you still start at app.myspec.dev; the MCP server is how you then pull those specs into your editor, keep them updated, and feed in local context.

Back to Homepage