MCP Integration

Connect AI tools to your Stellary workspace via the Model Context Protocol. Read live board state, create cards, manage documents, and run AI agent missions — all through a standard protocol your tools already support.

How It Works

Stellary exposes a Streamable HTTP MCP server at the /mcp path of your app URL. No separate process or installation needed — it is built into the Stellary backend.

Key principles:

• Stateless: Each request is independent — no session persistence needed
• Read + Write: AI can read boards, create/move cards, manage documents
• Human control: Supervised agents propose changes that humans approve or reject
• Fuzzy matching: Tools accept project/column/card names with typo tolerance
• Scoped access: Agents can be restricted to specific projects and tool sets

Setup Guide

You need a Bearer token to authenticate MCP requests. Three options are available:

Option A: Personal Access Token (recommended)

1. Log in to Stellary
2. Go to Settings → API Tokens
3. Click Create Token
4. Select scopes: projects:read, projects:write, pilotage:read
5. Copy the token (shown only once)

Option B: JWT Token

Call the login endpoint and use the returned access_token:

curl -X POST https://app.stellary.co/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"your-password"}'

# Response: { "access_token": "eyJhbG...", ... }

Option C: Static MCP Token (read-only, quick testing)

If your workspace administrator has configured a static MCP_TOKEN, you can use it for read-only access. This is useful for quick testing but does not support write operations.

# Use the static token
Authorization: Bearer your-mcp-token

Configure Your AI Tool

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "stellary": {
      "url": "https://app.stellary.co/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Then in Cursor: Settings → MCP → Refresh. You should see "stellary" with all available tools listed.

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "stellary": {
      "url": "https://app.stellary.co/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

Claude Code

Add the Stellary MCP server using the Claude Code CLI:

claude mcp add stellary \
  --transport streamable-http \
  https://app.stellary.co/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"

Any MCP Client

Point your MCP-compatible client to:

• URL: https://app.stellary.co/mcp
• Transport: Streamable HTTP (GET for discovery, POST for tool calls)
• Header: Authorization: Bearer YOUR_TOKEN

Authentication

The MCP endpoint supports three token types, checked in this order:

All MCP requests require a valid Authorization: Bearer header. Requests without a valid token are rejected with 401.

RBAC enforcement: Tool access is controlled by workspace roles and permissions. Each tool declares its required permissions (e.g. task.create, document.read), and the policy engine verifies the authenticated user has them before execution.

AI Agents

Stellary AI agents are workspace-scoped bot users that can operate on your boards and documents. Each agent is a dedicated user with its own identity, configurable tools, and autonomy settings.

Creating an Agent

Create agents in the Stellary UI under your workspace settings. Each agent has:

• Name and slug: Human-readable identifier (e.g. "DevBot", dev-bot)
• Description: What the agent is for
• Tools: Whitelist of allowed tool IDs (empty = all tools available)
• Autonomy mode: Controls how the agent handles write operations
• Scope: Restrict to specific projects
• MCP-only flag: When enabled, missions are queued instead of executed immediately

Autonomy Modes

Autonomy modes control how the agent handles write and collaboration tools. Read operations are always allowed regardless of autonomy mode.

Agent Tools Reference

Tools are organized into four categories. Each tool declares its required permissions and risk level. Tools exposed via MCP are marked with the mcp surface.

Board Read

Read-only tools for exploring projects, columns, cards, comments, subtasks, and labels.

Board Write

Tools for creating, updating, and moving cards. Require authentication and write permissions.

Board Collaboration

Tools for assigning cards and adding comments.

Document Operations

Tools for reading and writing project documents within mission context. Documents are scoped to the project and can be linked to cards.

Common Parameters

Most tools support fuzzy name matching. You can identify resources by ID or by name:

Fuzzy matching uses Levenshtein distance with a maximum edit distance of 2. If no match is found, the tool returns the top 3 suggestions with confidence scores so the AI can ask the user for clarification.

Missions

Missions are card-level AI tasks executed by agents. When you launch a mission on a card, an agent plans and executes a sequence of tool calls to achieve the objective described in the card.

Mission Lifecycle

• Queued: Mission is created and waiting for agent execution (MCP-only agents)
• Running: Agent is actively planning and executing tool calls
• Awaiting Approval: Supervised agent has generated proposals requiring human review
• Completed: All steps executed successfully, agent produced a summary
• Failed: Mission encountered an error or exceeded budget

Real-Time Streaming (SSE)

Mission progress is streamed in real time via Server-Sent Events (SSE). The event stream includes:

Each step is persisted to the MissionRun record, so mission history is always available even after the SSE connection closes.

Proposals

When a supervised or approval-mode agent attempts a write operation that requires human oversight, it generates a proposal instead of executing the action directly.

Proposal Workflow

1. Agent calls a write tool (e.g. create_cards_bulk, create_mission_document)
2. Policy engine checks the agent's autonomy mode and the tool's risk level
3. If approval is required, a proposal is created with the tool ID, input data, reasoning, and an expiration date
4. The human reviews the proposal in the Stellary UI
5. Approve: The tool is executed with the original parameters
6. Reject: The proposal is discarded, no action taken

Proposal data includes:

• Tool ID: Which tool the agent wants to call
• Input: The exact parameters the agent would pass
• Description: What the action would do
• Reason summary: Why the agent wants to perform this action
• Expiration: Proposals expire if not reviewed in time

Usage Examples

Explore Your Board

> "What's the current state of my Q1 Launch project?"

AI calls: list_projects
        → get_project_details(projectName: "Q1 Launch")
        → list_cards(projectName: "Q1 Launch")

AI responds: "Q1 Launch has 12 cards across 3 columns. Completion rate
is 42%. 2 cards are high priority and past due date..."

Create Tasks from a Spec

> "Create cards for the billing module based on the spec I just wrote"

AI calls: create_cards_bulk(projectName: "Q1 Launch", columnName: "To Do", cards: [
  { title: "Implement Stripe webhook handler", priority: "high" },
  { title: "Add billing API routes", priority: "high" },
  { title: "Create invoice PDF generation", priority: "medium" },
  { title: "Write billing integration tests", priority: "medium" }
])

Move Completed Work

> "Move the 'Auth flow migration' card to Done"

AI calls: move_card(projectName: "Q1 Launch", cardTitle: "Auth flow migration", columnName: "Done")

Assign and Comment

> "Assign the API routes card to alice@company.com and add a comment"

AI calls: assign_card(projectName: "Q1 Launch", cardTitle: "Add billing API routes",
                       memberEmail: "alice@company.com")
        → add_comment(projectName: "Q1 Launch", cardTitle: "Add billing API routes",
                      content: "Assigned to Alice per sprint planning discussion.")

Work with Documents

> "Create a technical brief for the payment integration card"

AI calls: get_mission_documents(projectId: "...", cardId: "...")
        → create_mission_document(projectId: "...", cardId: "...",
            title: "Payment Integration Brief",
            content: "## Overview\n...",
            docType: "brief")

Rate Limiting

MCP requests are subject to standard API rate limits based on your plan. Additionally, agent tool execution is governed by workspace-level and agent-level policies:

• Workspace plan limits: The number of AI operations per month depends on your subscription tier
• Agent tool whitelist: Each agent can be restricted to a subset of tools
• Project scope: Agents can be limited to specific projects — tool calls targeting other projects are rejected
• Concurrent missions: Only one mission can run on a card at a time; concurrent requests receive a 409 Conflict

Troubleshooting

401 Unauthorized

Your token is invalid, expired, or the wrong type. Check:

• Is the header format correct? Authorization: Bearer YOUR_TOKEN
• If using JWT: has it expired? (default: 7 days)
• If using PAT: is it revoked? Check in Settings → API Tokens
• If using a static MCP token: does it match the configured value?

403 Missing Permission

The authenticated user lacks the required permission for the tool. Check your workspace role and the tool's requiredPermissions (e.g. task.create, document.read). PAT tokens must include the relevant scopes.

Tool Returns "No projects found"

The user associated with your token has no projects in their workspace. Create a project first via the Stellary UI.

Agent Tool Call Rejected

If an agent's tool call is rejected, check:

• Is the tool in the agent's allowed tools list?
• Is the target project within the agent's configured scope?
• Does the agent's autonomy mode allow this type of operation?

409 Conflict on Mission

A mission is already running on this card. Wait for the current mission to complete, or check the mission status in the Stellary UI.

Cursor Doesn't Show MCP Tools

• Verify the URL in .cursor/mcp.json is correct: https://app.stellary.co/mcp
• Check that your token is valid and has appropriate permissions
• Click Refresh in Cursor's MCP settings
• Check the Cursor developer console for connection errors

Fuzzy Match Returns Wrong Resource

Use the exact ID (e.g. projectId, cardId) instead of a name for precise matching. Retrieve IDs from the corresponding list_* tool.