MCP Integration

MCP is the AI-native entry point into Stellary and the main way to connect Cursor, Claude Code, Claude Desktop, or any other Model Context Protocol client to live delivery data. Instead of mirroring the REST resource tree manually, an external client can connect to the built-in /mcp endpoint and operate through the same tool surface used by agents and runtime orchestration.

This page documents the real MCP server behavior implemented in the backend today: transport, identity model, tool registry exposure, queued missions, proposal handling, and plugin-backed extensions.

Overview

The MCP server is built directly into the NestJS backend. There is no separate daemon to run, no sidecar to deploy, and no custom bridge process to maintain.

Endpoint: https://app.stellary.co/mcp
Transport: Streamable HTTP
Methods: GET and POST
Auth header: Authorization: Bearer <token>
Session requirement: none

GET is useful for discovery / protocol negotiation.
POST carries the actual MCP requests.

The implementation creates a fresh stateless transport per request, specifically to stay compatible with MCP clients that do not persist a session identifier.

Need the broader product setup first? Start with Getting Started for workspace, token, and agent setup, or use the API Reference when you need to provision resources before an AI client enters the loop.

MCP vs REST

Use MCP when the caller is an AI client or an agent loop. Use REST when you need deterministic resource CRUD, explicit HTTP contracts, or traditional backend-to-backend integration.

If you need to create workspaces, projects, or billing flows before the AI layer comes into play, start from the API Reference and then attach MCP on top.

Transport

The transport is intentionally stateless. In practice, that means you can connect clients like Cursor without relying on a persistent Mcp-Session-Id.

Identity model

Stellary MCP has two primary operating modes: a human user connecting an AI client, or a dedicated workspace agent connecting with its own token.

This distinction matters because some tools need a workspace context. Human JWT/PAT clients can use the core board and cockpit flows, while agent tokens unlock workspace-context tools such as queued missions, mission documents, and plugin integrations.

Authentication

The controller resolves bearer tokens in layers. First it tries a normal user JWT, then a personal access token, and only then falls back to the optional static MCP_TOKEN.

Tool access is then enforced by project access, workspace permissions, agent tool whitelists, project scope, and autonomy policy. For agent tokens, write behavior depends on the configured autonomy mode.

Client setup

Every MCP client needs the same essentials: the https://app.stellary.co/mcp endpoint, Streamable HTTP, and an Authorization: Bearer header.

Cursor

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

Claude Code

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

Claude Desktop and similar clients

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

After connection, the first productive move is usually to call list_projects, then switch to exact IDs for the rest of the session.

If you still need to create a personal access token or an agent before connecting a client, follow Getting Started and the API token routes first.

Common workflows

In practice, the Stellary MCP server is usually used in three patterns: interactive workspace exploration, queued agent execution, and plugin-backed operational actions.

For the product surfaces behind those workflows, see Board & Cards, Documents & Context, and the Agents guide.

Tool surface

MCP tools are assembled from three places in the backend: legacy cockpit tools, the shared core tool registry, and installed workspace plugins. The result is one endpoint, but not one flat usage pattern.

Name-based convenience exists for several board tools and uses exact-or-fuzzy matching under the hood. Still, for serious runs and agent loops, you should discover IDs first and then reuse them explicitly.

If you want to understand the human-facing surfaces these tools operate on, read the board guide and the documents guide alongside this page.

Plugin tools

Plugin definitions are auto-registered into the same MCP surface when the plugin is installed and enabled in a workspace. Their tool IDs are prefixed by plugin slug.

Examples:
github:list_repos
github:create_pr
slack:post_message
email:send_email
discord:post_message

The codebase currently ships plugin definitions for GitHub, Slack, Email, and Discord. Those tools require a workspace context plus decrypted plugin configuration, so they are typically consumed through agent tokens.

Agent missions

MCP becomes especially powerful when paired with dedicated workspace agents. In that model, the app queues missions and the external MCP client becomes the execution loop.

1. Assign an active agent to a card in Stellary.
2. Launch a mission from the app.
3. If the agent is mcpOnly, the mission is queued instead of executed locally.
4. The external MCP client claims work with get_next_mission or long-polls with wait_for_mission.
5. Claiming a mission marks it as running and moves the card toward the in-progress column when possible.
6. The client finishes with complete_mission or fail_mission, which updates mission state and posts a card comment.

For agent tokens, stellary_init is the recommended bootstrap call. It returns autonomy mode, rules, skills, and the filtered tool list actually available to that agent.

Recommended agent loop:
1. stellary_init
2. get_next_mission or wait_for_mission
3. read card context and documents
4. execute tools with exact IDs
5. complete_mission or fail_mission

Approvals

Proposal behavior is driven by the tool policy layer. Only agent tokens participate in autonomy-policy proposal checks; a human using MCP acts directly as themselves.

MCP-only agents are forced to autonomous in the current backend, because their job is to pick up and execute queued work from an external client rather than wait for local polling.

Local development

In local development, if NODE_ENV is not production and MCP_TOKEN is not set, the controller lets unauthenticated requests reach the MCP transport. This makes local wiring easier, but it does not magically grant access to workspace data.

backend/.env example:
# MCP_TOKEN=your-secret-token

Without MCP_TOKEN in local dev:
- /mcp remains reachable
- current workspace tools still mostly require a user or agent identity

In production, or whenever MCP_TOKEN is configured, a bearer token is required before the transport is even reached.

Troubleshooting

401 invalid or expired token

Check the bearer format first. Then verify whether you are using a user JWT, a PAT, or an agent token that still exists and has not been revoked.

Tool says it requires a user token

You are probably connected with MCP_TOKEN or an anonymous local-dev request. Switch to a user JWT or a personal access token.

Tool says it requires a workspace context

That usually means you are trying to call an agent-only or plugin-backed tool from a human JWT/PAT session. Use an agent token tied to a workspace agent instead.

Plugin tool is visible but fails

The workspace plugin may not be installed or enabled, or its encrypted configuration may be missing. Plugin tools also require an agent/workspace context in the current MCP flow.

Fuzzy matching picks the wrong resource

Start with list_projects, list_cards, or another discovery tool, then reuse the exact IDs. That is the safest pattern for long-lived agent loops.

Related guides

These pages help connect MCP to the rest of the Stellary operating model, from resource provisioning to workspace agents and broader MCP strategy.