DevSpec
DevSpec
Sign In
Start Your Project
All Docs/MCP Endpoint

MCP Endpoint

The MCP (Model Context Protocol) endpoint opens DevSpec up to external coding tools. Claude Code, Cursor, Windsurf, and any MCP-compatible client can connect to DevSpec and access your project's accumulated knowledge, including decisions, conventions, code index, database schema, action items, resources, and session history. The tools can also write back, linking commits to sessions, updating action items, and adding implementation notes. DevSpec becomes the shared knowledge layer that all your coding tools tap into.

Why This Matters

Without the MCP endpoint, all the intelligence DevSpec accumulates is locked inside the web app. When you open Claude Code to write code, it has no idea what your team decided in a DevSpec session last week. The MCP endpoint fixes this. Your coding tool automatically gets access to every decision, convention, and piece of context your team has built up. Code stays consistent with team decisions without anyone having to remember or manually look things up.

How to Connect

Generate a token in DevSpec, paste the config snippet into your IDE, and you're connected.

Step 1 — Generate a token

  • Go to You → Connections in DevSpec.
  • Click Create token and choose a name (e.g. "Cursor - laptop").
  • Select a permission scope: read-only (query everything, cannot modify) or read-write (can also write data back).
  • Copy the token immediately — it is shown once and never again. Tokens are account-wide and work across every project you can access.

Step 2 — Copy the config snippet

After generating, DevSpec shows a ready-to-paste configuration snippet with the endpoint URL and your token pre-filled.

Step 3 — Paste and restart

Paste the snippet into your IDE's MCP config file and restart. The connection is established automatically and all 19 tools are discovered.

Connecting Claude Code

The recommended way to connect Claude Code is via the CLI. This ensures the Bearer token is set correctly and avoids common configuration issues.

Option 1 — CLI (recommended)

Run this command in your project directory, replacing the token with your own:

claude mcp add --transport http devspec https://devspec.ai/api/mcp \
  --header "Authorization:Bearer dvs_your_token_here"

Option 2 — Manual config file

Alternatively, add the config to your project's .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "devspec": {
      "type": "http",
      "url": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Verify it works

Run claude mcp list to confirm the status shows "Connected". Then start a new conversation and ask Claude to list your projects or search your knowledge base.

The /mcp dialog in Claude Code may show "needs authentication" even when the connection is working. This is a known cosmetic bug in Claude Code — the Bearer token auth works, but the UI does not reflect it. Run claude mcp list from the terminal to check the real status.

Connecting Cursor

The recommended path is the DevSpec Autopilot for Cursor extension (v0.2.0+), which auto-registers the MCP server and adds twelve command-palette skills. Manual MCP-only setup is also supported if you only want tool access without the workflow commands.

Step 1 — Install the extension

Pick either path (repo: https://github.com/DevSpecAI/cursor-devspec-plugin):

From GitHub release

  • Download the latest devspec-autopilot.vsix from the Releases page.
  • In Cursor: Ctrl+Shift+P → Extensions: Install from VSIX… → select the file.

From source

git clone https://github.com/DevSpecAI/cursor-devspec-plugin.git
cd cursor-devspec-plugin
npm install
npm run package   # produces devspec-autopilot.vsix

Then install the VSIX via Extensions: Install from VSIX… as above.

Step 2 — Restart Cursor

After installing or updating the VSIX, restart Cursor (Ctrl+Shift+P → Developer: Reload Window). DevSpec commands and the MCP server do not appear until the extension host reloads.

Step 3 — Connect your token

  • Run Ctrl+Shift+P → DevSpec: Set MCP token (or click Connect on the first-run "DevSpec: not yet configured" toast).
  • Paste your dvs_… token from You → Connections.
  • The extension writes the DevSpec server to ~/.cursor/mcp.json.

After changing the API URL or token, always open a new Agent-mode chat before running a skill. Cursor binds MCP availability at chat-thread-open time.

Step 4 — Install project rules

The extension adds always-on agent guidance at .cursor/rules/devspec.mdc — telling the agent to check DevSpec first, create/claim action items before editing, and tag commits with [devspec:<id>].

  • Automatic (default): rules install when MCP connects (devspec.autoInstallRules = always).
  • Manual: Ctrl+Shift+P → DevSpec: Install rules (requires a git repo).

Step 5 — Verify

  • Open Settings → MCP and confirm devspec shows green.
  • Confirm .cursor/rules/devspec.mdc exists in your repo.
  • Open a new Agent chat (Ctrl+L) and ask it to list your projects.
  • Open the command palette and confirm DevSpec commands appear.
  • Optional: run DevSpec: Verify connection to ping DevSpec.

MCP-only alternative

If you skip the extension, add a DevSpec MCP server entry manually:

{
  "mcpServers": {
    "devspec": {
      "url": "https://devspec.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer dvs_your_token_here"
      }
    }
  }
}

Save to ~/.cursor/mcp.json or your project .cursor/mcp.json, then restart Cursor.

Connecting Grok Build

Grok Build (xAI’s terminal coding agent) connects over Streamable HTTP MCP and can install the DevSpec plugin for skills such as /devspec-work and one-shot autopilot.

Validation host: examples use staging (https://staging.devspec.ai) until this integration is fully tested. At go-live, use https://devspec.ai (or your self-hosted host) and create the token on that same environment. The Connections UI always shows the host of the DevSpec app you are signed into.

Step 1: Create a token

Create a read-write MCP token under You → Connections (on the same environment as the MCP URL).

Step 2: Add the MCP server

grok mcp add --transport http devspec https://staging.devspec.ai/api/mcp \
  --header "Authorization: Bearer dvs_your_token_here"

Or add this block to ~/.grok/config.toml:

[mcp_servers.devspec]
url = "https://staging.devspec.ai/api/mcp"
headers = { Authorization = "Bearer dvs_your_token_here" }

Step 3: Install the DevSpec plugin (recommended)

grok plugin install DevSpecAI/DevSpec-Grok-Build-Plugin --trust

From a local clone: grok plugin install ./DevSpec-Grok-Build-Plugin --trust.

Step 4: Verify

Run grok mcp list or grok inspect, then in the Grok TUI ask it to list your DevSpec projects. Optionally run the devspec-verify-connection skill.

See the Autopilot Runners doc for unattended one-shot runs (grok --always-approve -p '…').

Connecting Other MCP Clients

Any MCP-compatible client (Windsurf, Continue, or others) works the same way. No plugins or adapters are needed — DevSpec uses the standard MCP Streamable HTTP transport.

What you need

Check your client's documentation for where to configure remote MCP servers.

Plugin Commands — A Simpler Way

If you're using Claude Code with the DevSpec plugin installed, you don't need to call these MCP tools directly. The plugin provides ready-made slash commands like /devspec.work, /devspec.create, and /devspec.commit that wrap these endpoints with formatted output and smart defaults.

See the Plugin Commands docs for the full list of 16 commands and 1 skill available in Claude Code.

Cursor users get the same workflows via the DevSpec extension's command palette (Ctrl+Shift+P → type "DevSpec"). Twelve skills cover work, brainstorm, create, session handoff, verify, help, link, commit, and one-shot autopilot (process / status / history). See the Autopilot Runners doc for the full Cursor workflow, including batch mode with --items=uuid1,uuid2.

Grok Build users install the DevSpec plugin (grok plugin install DevSpecAI/DevSpec-Grok-Build-Plugin --trust) and use skills such as /devspec-work and devspec-autopilot. Unattended runs use grok --always-approve -p 'Use the devspec-autopilot skill' (single quotes — safer when pasting into a terminal).

What Your Coding Tool Can Read (13 Tools)

When your coding tool connects via MCP, it automatically discovers these 13 read tools. The AI can call any of them at any time to find the information it needs. All results include metadata like timestamps, confidence levels, and source session references.

NameScopeDescription
List ProjectsreadSee all DevSpec projects you own. This is the only tool that works across projects — all others are scoped to the token's project.
Get Project SummaryreadGet a high-level overview of the project: linked repos, connected databases, index stats, and recent activity.
Search IndexreadSearch the code index for symbols, files, patterns, or keywords. DevSpec has already parsed your codebase and categorised every file, so the AI can search for "all authentication-related files" or "functions that handle payments" and get structured results.
Read FilereadRead the contents of a specific file from your tracked repository (GitHub, Bitbucket, GitLab, or Gitea). Supports optional line ranges to avoid loading entire large files.
Get Database SchemareadRetrieve the current schema of your connected database — tables, columns, types, constraints, and relationships. Optionally filter to a single table.
Get Action ItemsreadList tasks, bugs, and follow-ups tracked within the project. Filter by status (open, completed, or all).
Get ResourcesreadList documents and artifacts attached to the project — ADRs, guides, checklists, plans, summaries, conventions, and runbooks. Optionally filter by type.
Get Session TranscriptreadRetrieve the full conversation record of a past DevSpec session, including user messages, AI responses, and tool call results.
Get Recent SessionsreadList recent sessions with summaries and timestamps. Useful for orientation — "what has the team been discussing recently?"
Search KnowledgereadThe primary knowledge search tool. Search across all knowledge entries by keyword, with optional type filtering (decisions, conventions, risks, patterns). Superseded and retracted entries are excluded by default so the AI gets the current truth.
Get DecisionsreadList architecture and design decisions recorded for the project, ordered by most recent first.
Get ConventionsreadList coding conventions and standards the team has established — naming patterns, error handling approaches, branching strategies, etc.
Get Unresolved QuestionsreadList open questions and unknowns flagged during sessions that have not yet been resolved. Useful so the AI knows what is still being debated and should not be assumed.

What Your Coding Tool Can Write Back (6 Tools)

With a read-write token, the endpoint also exposes these 6 write-back tools. They close the loop — implementation details flow back into DevSpec automatically. Every write-back records who did it and when, creating a complete audit trail.

NameScopeDescription
Update Action Itemread-writeUpdate an existing action item's status (e.g. mark as completed or in progress). Can include a note and a commit reference.
Create Action Itemread-writeCreate a new tracked task in DevSpec. If the AI discovers a bug or identifies follow-up work during implementation, it can create a task directly.
Add Commit Referenceread-writeLink a git commit to the project, optionally connecting it to a specific session, action item, or knowledge entry.
Add Implementation Noteread-writeAdd a follow-up note with optional references (commits, PRs, files). For recording context about how something was implemented.
Create Resourceread-writeCreate a new resource (document, link, reference) in the project. An external tool could generate implementation summaries or documentation and store them in DevSpec.
Add Schema Changeread-writeRecord a database migration event — migration reference, description, and what changed (tables added, modified, or dropped).

How It Finds the Right Information

The knowledge system is designed so the AI always gets the current truth, even when topics have been discussed across many sessions over weeks.

Project scoping

Each token is scoped to one project, so there is no cross-project confusion.

Knowledge versioning

The knowledge system maintains versioned, stateful entries rather than raw conversation fragments. When a decision evolves over multiple sessions (e.g. switching from Redis to Memcached for caching), the system tracks the full thread but returns only the current, non-superseded state by default.

Search capabilities

  • Keyword and semantic search across all knowledge entries.
  • Type filters: decisions, conventions, risks, patterns.
  • Tag filters for topic-based narrowing.
  • Superseded entries excluded by default — the AI gets the latest truth.

The Full Loop

The MCP endpoint enables a complete feedback loop. The knowledge compounds over time.

  • Your team discusses architecture in a DevSpec session.
  • The AI captures decisions, conventions, and action items.
  • You open your coding tool and it reads those decisions via MCP.
  • You write code consistent with the team's choices.
  • Your tool writes back commit references, action item updates, and implementation notes.
  • The next DevSpec session has even more context — and the cycle repeats.

Managing Tokens

Token management is designed to be simple with sensible defaults.

  • Any project member can create up to 10 tokens per project.
  • Tokens never expire — they stay active until explicitly revoked.
  • Revoke a token at any time from project settings; the effect is immediate.
  • Each token tracks its last-used date so you can spot stale tokens.
  • If a user is removed from a project, all their tokens are automatically invalidated.

Supported Clients

The endpoint works with any MCP-compatible client. No client-specific configuration or plugins are needed — the MCP protocol handles tool discovery automatically.

Confirmed clients

  • Claude Code — Anthropic's CLI for Claude.
  • Cursor — AI-native code editor.
  • Grok Build — xAI's terminal coding agent.
  • Windsurf — AI-powered IDE.
  • VS Code (Copilot) — with MCP extension support.
  • Any future MCP-compatible client.

Troubleshooting

Common issues and how to resolve them.

Claude Code shows "failed" or "needs authentication"

The /mcp dialog shows a failed or unauthenticated status even though the server is reachable.

Why this happens

Claude Code runs an OAuth discovery flow (probing .well-known endpoints) before connecting. Since DevSpec uses static Bearer tokens instead of OAuth, this discovery fails and the UI caches the "failed" state. The /mcp Reconnect and Authenticate buttons only retry OAuth — they do not attempt a fresh Bearer token connection.

Fix: remove and re-add via CLI

This clears the cached failed state and forces a clean connection:

claude mcp remove devspec -s local
claude mcp add --transport http devspec https://devspec.ai/api/mcp \
  --header "Authorization:Bearer dvs_your_token_here"

Run claude mcp list to confirm the status is "Connected". The /mcp dialog may still show "needs authentication" — this is a known cosmetic bug. The tools will work regardless.

Tools not loading in conversation

claude mcp list shows "Connected" but tools are not available in the conversation.

  • MCP tools are discovered when a conversation starts, not mid-session. If you added or re-added the server during a conversation, start a new conversation for tools to appear.
  • Ask Claude to "list my DevSpec projects" — this forces tool discovery.
  • Verify with claude mcp list that the status is "Connected" (not "Failed").

Connection refused or timeout

Your IDE cannot reach the DevSpec endpoint.

  • Check the endpoint URL is correct: https://devspec.ai/api/mcp (production) or http://localhost:3000/api/mcp (local dev).
  • Ensure the DevSpec server is running if using local dev.
  • Check for firewall or proxy restrictions blocking the connection.
  • Test the endpoint directly: curl -s -X POST https://devspec.ai/api/mcp -H "Authorization: Bearer dvs_your_token" -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

401 Unauthorized

Your token is invalid or has been revoked.

  • Generate a new token from the project's API Tokens tab.
  • Make sure you copied the full token (starts with dvs_).
  • Check that the Authorization header format is exactly: Bearer dvs_your_token_here (no extra spaces or line breaks).
  • If using the CLI, use --header "Authorization:Bearer dvs_..." (no space after the colon).

429 Too Many Requests

You have exceeded the rate limit of 60 requests per minute.

Wait a few seconds and retry. The rate limit resets within one minute. If you consistently hit this limit, consider reducing the frequency of tool calls in your workflow.

Server exists in multiple scopes

claude mcp remove fails because the server is defined in both local config and .mcp.json.

Remove from the specific scope:

claude mcp remove devspec -s local    # ~/.claude.json
claude mcp remove devspec -s project   # .mcp.json