SpecDeck
Sign inStart free
Docs/The MCP server
FOR AI AGENTS

The MCP server: one URL, one workspace.

The SpecDeck MCP server lets AI coding agents read specifications, claim goals, do the work, and post questions back to your team. Point any MCP-compatible agent at one URL and approve OAuth in the browser. No tokens to copy or paste.

MCP ENDPOINT
https://app.specdeck.ai/mcp

How connecting works

SpecDeck uses OAuth to connect AI agents. You never copy or paste a token. The flow is:

  1. 1
    You add the SpecDeck MCP URL to your agent.
  2. 2
    The agent opens your browser to SpecDeck's authorization screen.
  3. 3
    You sign in if needed, pick which workspace the agent may access, and approve.
  4. 4
    The agent receives a token scoped to that one workspace and uses it for every request.
◆
Tokens are workspace-scoped
The token is tied to a single workspace. To let an agent work in a different workspace, connect again and pick that workspace.

Two kinds of agent support

Coding agents fall into two groups:

NATIVE
Native remote MCP
The agent speaks HTTP MCP and runs the OAuth flow for you. You give it the URL and nothing else. Most current agents are here.
BRIDGE
Local (stdio) MCP only
Bridge to the remote server with mcp-remote, a small adapter run through npx. It handles OAuth and proxies the connection.

The universal stdio bridge command is:

STDIO BRIDGE
npx -y mcp-remote https://app.specdeck.ai/mcp

Connecting each agent

After you add the server, trigger the connection so the OAuth screen opens (each section says how). Approve access and pick a workspace. The agent is then ready.

Add the server with the CLI:

TERMINAL
claude mcp add --transport http specdeck https://app.specdeck.ai/mcp

Then run /mcp inside Claude Code and select specdeck to authenticate. The browser opens the SpecDeck approval screen.

Use --scope user to make the server available across all your projects, or --scope project to share it with your team through a checked-in .mcp.json.

Any other agent

If your agent supports remote HTTP MCP servers, give it https://app.specdeck.ai/mcp and let it run OAuth. If it only supports local command-based servers, point it at the mcp-remote bridge command shown above.

A typical agent workflow

A common end-to-end flow for an AI agent connected to SpecDeck:

  1. 1
    list_specifications and read_specification to understand the project.
  2. 2
    create_goal to record a task linked to a spec, or list_goals to find existing work.
  3. 3
    get_next_goal to claim the highest-priority idle goal. It assigns the goal to you and sets it to in_progress.
  4. 4
    read_goal to load the linked sections, status, and prior context.
  5. 5
    Do the implementation work. When something is unclear, ask_question or ask_spec_question — both pause the goal until a person answers.
  6. 6
    If the spec is wrong or incomplete, create_draft, update_draft, and create_proposal to draft a fix, then propose_spec_change to raise it on the goal.
  7. 7
    submit_goal with the artifacts you produced (branch, pull request, deployment) to mark the goal done.
✓
Humans in the loop
Throughout, your team watches the goal's activity stream in the web app, answers questions, and reviews proposals.

Onboard an existing codebase

Already have a codebase with no specs? Point a connected AI coding agent at SpecDeck and run the onboard_codebase prompt. By default it posts a short plan for you to approve, then builds everything without stopping again. It reads the repository, creates the areas the system splits into, then writes foundational docs and a spec for every feature, all as proposals you review and publish. Approve the plan and come back to a review queue that covers the whole codebase.

◆
The proposal queue is your review gate
Nothing goes live until you publish it. Every spec arrives as a proposal you publish or reject in the merge screen. By default the agent stops once for you to approve its plan, then builds everything. Run it with mode: autonomous to skip even that checkpoint, or mode: interactive to also review each document one at a time.

Run it

  1. 1
    Connect a coding agent to the SpecDeck MCP server, as described above.
  2. 2
    Run the onboard_codebase prompt in the agent. Agents that list MCP prompts show it as a slash command.
  3. 3
    Read the short plan it posts in chat, then approve it (or cut and reorder first). From there it creates areas and proposals across the codebase without stopping.
  4. 4
    Review the proposals in the SpecDeck merge screen and publish the ones you want.

Options

The prompt takes five optional arguments:

focus_path limits the survey to one directory, for example services/billing. Omit it to cover the whole repository.

mode sets how it runs: plan_first (the default) stops once for you to approve the plan, then builds everything without stopping again; autonomous runs start to finish without stopping, creating proposals for everything the code implements; interactive proposes a plan, waits for your approval, and works one document at a time.

output decides where each spec lands, independent of mode: proposals (the default) routes every spec through the review queue for you to publish, while published publishes each one directly, live at once, with no review queue.

depth sets how far to go: full (the default) for foundational docs plus a spec for every feature, or foundational_only to stop after the foundational docs.

max_feature_specs caps how many feature specs to propose. Omit it to cover every feature in the code.

◆
This runs on the coding-agent side
The onboard_codebase prompt runs through MCP, on the agent that writes your code. The in-app Assistant is separate: it helps people author specs by hand and never touches code.

Tool reference

Every tool runs against the workspace the agent's token is scoped to. Tools that need an ID expect IDs returned by other tools, such as a specification_id from list_specifications or a goal_id from list_goals.

SPECIFICATION TOOLS
Read & write specifications

list_specificationsTOOL

List every specification in the workspace, with each spec's scope.

NO PARAMETERS
read_specificationTOOL

Read a spec with all its sections, including published content and any in-progress drafts and proposals.

specification_idstringREQUIRED
The spec to read.
create_specificationTOOL

Create a new spec. Feature scope creates product and engineering sections. Foundational scope creates one foundational section.

titlestringREQUIRED
Display title.
scope"feature" | "foundational"REQUIRED
The spec type.
templatesobjectOPTIONAL
An object mapping section names (product, engineering, or foundational) to template IDs from list_templates.
rename_specificationTOOL

Change the title of an existing specification. Scope, sections, and content are not affected.

specification_idstringREQUIRED
The spec to rename.
titlestringREQUIRED
The new title.
read_sectionTOOL

Read one section of a spec. Returns the published version by default.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The section to read.
branch_idstringOPTIONAL
Read an in-progress draft or proposal instead.
versionnumberOPTIONAL
Read a historical published version number.
branch_id and version cannot both be set.
create_draftTOOL

Create an editable copy of a section from its current published content.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The section to copy.
goal_idstringOPTIONAL
Link the draft to a goal so the team sees what it is for.
update_draftTOOL

Overwrite the content of a draft.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The owning section.
branch_idstringREQUIRED
The draft to update.
contentmarkdownREQUIRED
The new Markdown content.
create_proposalTOOL

Mark a draft ready for human review. The draft becomes read-only until a person publishes or rejects it.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The owning section.
branch_idstringREQUIRED
The draft to submit.
publish_draftTOOL

Publish a draft straight to the live spec, skipping human review. Its content is merged into the published section at once. Use create_proposal instead when a person should review first.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The owning section.
branch_idstringREQUIRED
The draft to publish.
add_commentTOOL

Post a comment on an edit or a published section.

specification_idstringREQUIRED
The owning spec.
section_idstringREQUIRED
The owning section.
branch_idstringREQUIRED
The edit or section to comment on.
contentstringREQUIRED
The comment text.
◆
Specs render Mermaid diagrams
Specification content is plain Markdown, so the read and write tools return it untouched. AI agents can include a fenced code block tagged mermaid in any section content, and it renders as a diagram for human readers in the published and read views, goal views, and the Markdown editor preview. Nothing extra to enable.
SECTION CONTENT
```mermaid
flowchart LR
  A[Request] --> B[Auth service]
  B --> C[API]
```

GOAL TOOLS
Create and run goals

list_goalsTOOL

List goals in the workspace.

status"idle" | "in_progress" | "done"OPTIONAL
Filter by status.
read_goalTOOL

Read a goal with its linked specification sections, status, assignee, activity stream, and artifacts (branches, PRs, deployments, reports).

goal_idstringREQUIRED
The goal to read.
create_goalTOOL

Create a goal linked to a specification. It starts idle and unassigned.

specification_idstringREQUIRED
The linked spec.
titlestringREQUIRED
A concise title, under 80 characters.
summarymarkdownOPTIONAL
Detailed analysis of what to implement and why.
acceptance_criteriamarkdownOPTIONAL
Testable conditions that define done.
get_next_goalTOOL

Atomically claim the highest-priority idle goal, assign it to yourself, and set it to in_progress. Goals with an open blocking action are skipped until it is resolved. Returns no_goals_available when nothing is claimable.

NO PARAMETERS
submit_goalTOOL

Mark a goal done. Use it when your work is complete. Optionally attach the artifacts the work produced — they are recorded on the goal before it is marked done.

goal_idstringREQUIRED
The goal.
artifactsobject[]OPTIONAL
Artifacts the work produced — each with a type, value, and (for deployments) an environment.
update_goalTOOL

Update a goal's status and/or its assignee. Reassigning a goal is how work is handed off. To mark a goal done prefer submit_goal.

goal_idstringREQUIRED
The goal.
status"idle" | "in_progress" | "done"OPTIONAL
The new status.
assignee_idstringOPTIONAL
User ID to assign the goal to — a human or an agent.
ask_questionTOOL

Ask the human a blocking question about a goal. The goal flips back to idle in the same transaction — work pauses until a person resolves it.

goal_idstringREQUIRED
The goal.
contentmarkdownREQUIRED
The question text.
ask_spec_questionTOOL

Like ask_question, but scoped to a specification decision. Use it when the question is about whether or how the spec should change. Blocks the goal until resolved.

goal_idstringREQUIRED
The goal.
contentmarkdownREQUIRED
The spec-related question.
propose_spec_changeTOOL

Propose a concrete spec change by linking a draft or proposal branch you already created. The goal flips back to idle until the suggestion is resolved; it auto-resolves when the branch is published or deleted.

goal_idstringREQUIRED
The goal.
spec_branch_idstringREQUIRED
The draft or proposal branch you created.
contentmarkdownREQUIRED
Why this change is needed.
add_artifactTOOL

Record an artifact on a goal — evidence of the work: a branch, commit, pull request, deployment, test report, or CI run. Visible via read_goal.

goal_idstringREQUIRED
The goal.
type"branch" | "commit" | "pull_request" | "deployment" | "test_report" | "ci_run"REQUIRED
The artifact kind.
valuestringREQUIRED
The branch name, commit SHA, or URL.
environment"local" | "dev" | "qa" | "stage" | "prod"OPTIONAL
Required for type deployment; omit for every other type.
update_artifactTOOL

Update an existing artifact's value or environment — for example, correct a deployment URL. Type and authorship are fixed at creation.

goal_idstringREQUIRED
The goal.
artifact_idstringREQUIRED
The artifact to update.
valuestringOPTIONAL
New value.
environment"local" | "dev" | "qa" | "stage" | "prod"OPTIONAL
New deployment environment.
remove_artifactTOOL

Remove an artifact from a goal.

goal_idstringREQUIRED
The goal.
artifact_idstringREQUIRED
The artifact to remove.

TEMPLATE TOOLS
Starter content

list_templatesTOOL

List the document templates available as starter content for new spec sections. Each template has a kind that must match the section it fills.

kind"product" | "engineering" | "foundational"OPTIONAL
Filter to one section kind.
CONTINUE READING
FOR HUMANS
The web app
Workspaces, specs, the merge screen, and the goal lifecycle.
→