How to Connect AI Agents to Stellary via MCP

Stellary exposes a native Model Context Protocol (MCP) server for AI clients and external agent loops. A connected client can discover project tools, read live delivery context, and perform the actions allowed by its identity and permissions.

This guide covers the production setup currently implemented by Stellary: Streamable HTTP on https://api.stellary.co/mcp, bearer authentication, and separate identity models for human users and workspace agents.

For the complete runtime reference, see the Stellary MCP documentation.

What MCP Does — and Does Not Do

MCP standardizes communication between an AI application and a server that exposes tools, resources, or prompts. It reduces the amount of client-specific integration work, but it does not guarantee that every MCP client supports the same transport, authentication flow, or capabilities.

With Stellary, the MCP server is built into the backend. There is no separate daemon or bridge to deploy. The server uses Streamable HTTP and accepts GET for discovery or protocol negotiation and POST for MCP requests.

Before You Connect

You need:

• a Stellary workspace with at least one accessible project;
• a client that supports MCP over Streamable HTTP and custom authorization headers;
• either a personal access token for interactive use or an agent token for a dedicated agent loop.

The token is not just a transport secret. It determines the identity, project access, tool surface, and write behavior available to the client.

Step 1: Choose the Right Identity

Personal access token

Use a personal access token (PAT) when Cursor, Claude Code, Claude Desktop, or another interactive client should act as you. Project and cockpit tools still respect your Stellary access and the scopes granted to the token.

Create the token from Settings > API Tokens. Start with:

• projects:read for boards, cards, documents, and project context;
• pilotage:read for cockpit and steering signals.

Add projects:write or pilotage:write only when the client needs those actions. Stellary also supports notifications:read, account:read, and account:write for the corresponding REST surfaces.

You can also create a PAT through the API while authenticated with a user session:

curl -X POST https://app.stellary.co/api-tokens \
  -H "Authorization: Bearer YOUR_USER_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name":"Cursor MCP","scopes":["projects:read","pilotage:read"]}'

The plaintext secret is returned only when the token is created. Store it in your client's secure configuration and revoke it if it is exposed.

Agent token

Use an agent token when a dedicated workspace agent needs to claim queued missions, access agent-specific context, or use installed plugin tools. The token is tied to that agent's workspace, project scope, tool whitelist, rules, and autonomy mode.

For an external agent loop, call stellary_init first. It returns the agent's effective rules, skills, autonomy mode, and available tools before work begins.

The optional server-side MCP_TOKEN is only a transport barrier. By itself, it does not provide the user or workspace-agent identity required by most Stellary tools.

Step 2: Configure the MCP Client

Use the following values:

• Endpoint: https://api.stellary.co/mcp
• Transport: Streamable HTTP
• Header: Authorization: Bearer YOUR_TOKEN_HERE
• Persistent MCP session ID: not required

For clients that use an mcpServers JSON object:

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

For Claude Code:

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

Client configuration formats can change. Keep the endpoint, transport, and authorization header above, then follow the current configuration syntax of your chosen client.

Step 3: Verify the Connection

After connecting, ask the client to list its MCP tools. Then make a read-only call such as list_projects.

A useful first check is:

1. call list_projects;
2. select an exact project ID;
3. call list_cards or get_project_details with that ID;
4. confirm that the returned workspace and project match the intended scope.

Stellary can resolve some names, but exact IDs are safer for long-running agents and repeatable workflows.

What the Stellary MCP Server Exposes

The available list depends on the connected identity and installed plugins. Core tool families include:

• Board reads — list_projects, get_project_details, list_cards, get_card_details, and get_card_comments;
• Board and collaboration writes — create_card, move_card, update_card, assign_card, and add_comment;
• Cockpit and supervision — get_pilotage_state, get_cockpit_dashboard, get_agent_status, and list_pending_proposals;
• Agent runtime — stellary_init, get_next_mission, wait_for_mission, complete_mission, and fail_mission;
• Plugin tools — workspace integrations such as GitHub, Slack, Email, Discord, or X when the plugin is installed, enabled, and available to the agent.

Tool discovery is the source of truth for a specific connection. A PAT, an agent token, and a transport-only token do not expose identical capabilities.

Configure Write Behavior Deliberately

For agent tokens, Stellary applies the autonomy mode configured on the agent:

A human connected with a JWT or PAT acts as that user; agent-autonomy proposal checks apply specifically to agent tokens. Project permissions and PAT scopes still constrain access.

Start with read scopes, verify the context returned by the server, then grant only the write scopes and tools required by the workflow. Use approval for a new agent or a high-impact project until its behavior is predictable.

Troubleshooting

The server returns 401

Confirm that the header uses Bearer <token>, that the token has not expired or been revoked, and that the client actually sends custom headers with Streamable HTTP.

A tool requires a user token

You are probably using the static MCP_TOKEN or an anonymous local-development connection. Switch to a user JWT or PAT.

A tool requires workspace context

The tool is likely agent-only or backed by a workspace plugin. Use an agent token tied to the correct workspace agent.

A write becomes a proposal

This is expected for an agent in approval mode and for protected tools in supervised mode. Review the proposal in Stellary or change the agent's autonomy policy only after evaluating the risk.

A plugin tool is missing or fails

Check that the plugin is installed and enabled in the workspace, its configuration is complete, and the connected agent is allowed to use it.

Once the connection works, use automations for deterministic event-driven rules and MCP for interactive clients or agent loops that need live context and tool discovery.