All docs
MCP Integration

Getting Started

Connect an AI agent to your AI StackWorks board in three steps — register the server, paste your token, and create your first card over MCP.

AI StackWorks exposes a Model Context Protocol server so an AI agent can read and write your project's records — cards, tasks, ideas, and changelog entries — directly over HTTP. Anything an agent reads is exactly what you see in the dashboard, because the database is the single source of truth.

This guide gets an agent connected and driving your board in three steps.

What you need

  • An AI StackWorks project. Each project maps 1:1 to one of your git repos.
  • A project API key — minted from the in-app Getting started page, under Connect your repo to this project. It is shown once and stored hashed, so copy it somewhere safe. Treat it like a password: it grants read/write access to that project's records.
  • Any MCP-capable client (Claude Code, or any editor/agent that speaks streamable-HTTP MCP).

The endpoint

POST https://app.aistackworks.com/api/mcp/

The server runs in stateless mode — one JSON response per request, no server-side session. You authenticate every request with a bearer token; see Authentication for the token model.

Step 1 — Register the server

Add AI StackWorks to your client the same way you'd register any MCP server.

// mcp.json — alongside your other MCP servers
{
  "mcpServers": {
    "aistackworks": {
      "type": "http",
      "url": "https://app.aistackworks.com/api/mcp/",
      "headers": { "Authorization": "Bearer <your-project-api-key>" }
    }
  }
}

For Claude Code, one command does the same — run it from inside the repo so the server is scoped to that project:

claude mcp add --transport http aistackworks \
  https://app.aistackworks.com/api/mcp/ \
  --header "Authorization: Bearer <your-project-api-key>"

Step 2 — Confirm the tools are discovered

You don't teach the agent anything. On connect it runs the MCP handshake (initialize → tools/list) and auto-discovers every tool — their names, descriptions, and argument schemas come straight from the server.

In Claude Code, run /mcp. You should see aistackworks connected and its tools listed. The full set is documented in the Tools Reference.

Step 3 — Create your first card

Ask the agent to create a card, or call the tool directly:

create_card(
  title="Add CSV export to the reports page",
  body="Users want to download the report as CSV.",
  type="Feature",
  priority="Medium"
)

The card lands in your Backlog and the tool returns its id. From there the agent can take it the rest of the way:

approve_card(card_id="<id>")     →  moves it to Plan Approved
dispatch_card(card_id="<id>")    →  sends it to the agent fleet (Ready for Dev)

dispatch_card kicks off the build → test → review → docs → ship pipeline. If a project has no agent host connected yet, the card still moves but nothing runs until one is enrolled — the reply tells you so.

That's the whole loop: an orchestrator can create, approve, dispatch, and update cards end to end with a single project-scoped token.

Next steps

  • Authentication — token kinds, scoping, and the ?project= selector for account-wide keys.
  • Tools Reference — every tool, its arguments, and what it returns.
Next
Authentication