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://api.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

An OAuth connection belongs to one workspace and can authorize you, one or more active agents, or both. Existing direct credentials remain supported.

Call stellary_list_identities to get opaque references. With one identity, actingAs is implicit. With multiple identities, actingAs is required on every call, including stellary_init and mission tools.

Authentication

OAuth 2.1 with discovery, dynamic client registration, and PKCE S256 is the recommended public flow. Clients get a one-hour access token and can renew with a rotating refresh token when offline_access is granted.

Access is rechecked on every call: credential scopes, project access, workspace permissions, agent status and policy, autonomy, and the mission snapshot stay authoritative. Suspending an agent disables it immediately without disconnecting the grant’s other identities.

Client setup

Add only the https://api.stellary.co/mcp endpoint in an OAuth-capable client. It discovers Stellary, opens the browser consent flow, and returns with its tokens. No PAT needs to be copied into the client configuration.

Cursor

{
  "mcpServers": {
    "stellary": {
      "url": "https://api.stellary.co/mcp"
    }
  }
}

Claude Code

claude mcp add stellary \
  --transport http \
  https://api.stellary.co/mcp

Claude Desktop and similar clients

{
  "mcpServers": {
    "stellary": {
      "url": "https://api.stellary.co/mcp"
    }
  }
}

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

For a legacy client without OAuth, create a personal access token through the API token routes and add it as a bearer. OAuth remains the recommended path for every new connection.

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
x_create_draft

The codebase currently ships plugin definitions for GitHub, Slack, Email, Discord, and X. 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 keep the autonomy mode configured in Stellary. In approval mode, non-read writes become persisted proposals, even when the execution client is external.

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

An OAuth client should follow the WWW-Authenticate challenge and open Stellary consent. For a direct credential, verify the bearer format, expiry, and revocation state.

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

With multiple OAuth identities, call stellary_list_identities and provide actingAs. For an agent project action, claim a mission first so the call has a valid missionRunId.

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.