Connect Cursor to a Live Project Board over Hosted MCP (Streamable HTTP)

I’m Soheil Saheb-Jamii (Anymfah). I built Stellary’s MCP surface so an AI host talks to the same NestJS backend as the app — not a toy wrapper and not a local stdio process you have to babysit.

This post is a setup guide. By the end you should have the endpoint in your client, a read-only credential, and one successful list_projects call.

What it does inside Cursor / Claude Desktop

Once connected, the host sees Stellary tools the same way it sees any other MCP server. Typical Agent loop:

• Discover which projects you can access
• Pull cards for a project ID
• Read cockpit / pilotage signals for the workspace
• Optionally create or move cards, or claim queued agent missions

No separate daemon. No npx package. Transport is hosted Streamable HTTP at:

https://api.stellary.co/mcp

GET is useful for discovery / negotiation; POST carries MCP requests. The server creates a fresh transport per request, so clients that do not persist Mcp-Session-Id still work.

Add the server (copy-paste)

Prefer OAuth when the client supports it. In Cursor or Claude Desktop-style configs, URL-only is enough — the client discovers Stellary, opens consent, and stores tokens. No PAT in the file.

Drop that in ~/.cursor/mcp.json (global) or .cursor/mcp.json (project), or the equivalent MCP settings UI. Restart / reload MCP tools until stellary shows as connected.

PAT fallback (no OAuth yet)

If your client cannot complete OAuth, create a personal access token in app.stellary.co under Account settings → API tokens. Start with:

• projects:read — boards, cards, documents, project context
• pilotage:read — cockpit and steering signals

A PAT acts as you (the human). Workspace membership and project access still apply on every call. Add write scopes only after the read path works.

Put the secret in an environment variable — never paste a raw token into the article, git, or a shared gist:

{
  "mcpServers": {
    "stellary": {
Export `STELLARY_TOKEN` in the environment that launches the IDE / MCP host. Revoke the token if it ever leaks.

## First read-only checks

Ask the agent (or call tools manually) in this order. Stay on reads until the IDs look right.

1. **`list_projects`** — confirm the workspace and project list match what you see in the app.
2. **`list_cards`** (or `get_project_details`) with an **exact project ID** from step 1 — fuzzy name matching exists, but IDs are safer.
3. **Cockpit** — `get_cockpit_dashboard` or `get_pilotage_state` with `pilotage:read` — sprint / steering signals without opening the browser.

If `list_projects` fails with 401, the host is not sending a valid Bearer (OAuth session expired, missing header, or env var not visible to the client process). Fix auth before adding write scopes.

## Tools overview (board / cockpit / missions)

Exact tool lists depend on identity and installed plugins. At a high level:

| Area | What you use it for | Examples |
| --- | --- | --- |
| **Board** | Inspect and change delivery work | `list_projects`, `list_cards`, `get_card_details`, `create_card`, `move_card`, `assign_card`, `add_comment` |
| **Cockpit** | Supervision and steering | `get_pilotage_state`, `get_cockpit_dashboard`, `get_agent_status`, `list_pending_proposals` |
| **Missions** | External agent loops against queued work | `stellary_init`, `get_next_mis
Full registry and edge cases live in the docs — this post is the minimum path to a live read.

## Permissions worth remembering

- **PAT = human identity.** Same access you have in the UI, narrowed by token scopes.
- **Start read-only:** `projects:read` + `pilotage:read`.
- **Writes:** add `projects:write` / `pilotage:write` only when you need them.
- **Every call is rechecked:** scopes, project membership, agent status, and mission context stay authoritative. Suspending an agent or revoking a token takes effect immediately.

## Links

- Docs: [https://stellary.co/docs/mcp/](https://stellary.co/docs/mcp/)
- Repo: [https://github.com/Anymfah/stellary-mcp](https://github.com/Anymfah/stellary-mcp)
- App: [https://app.stellary.co](https://app.stellary.co)

## Cover image note

Use a screenshot of the Stellary Kanban board from the app (columns + cards). Upload it as the Dev.to cover; keep the path/filename local to your editor — do not invent a CDN URL here.

---

That’s the whole first mile: URL in `mcp.json`, OAuth or `STELLARY_TOKEN`, then `list_projects` → cards → cockpit. If something breaks, check Bearer format and that the MCP host process can see the env var before you dig into tool names.sion` / `wait_for_mission`, `complete_mission`, `fail_mission` |

Interactive use with a human PAT: board + cockpit first. Queued missions and most plugin tools (GitHub, Slack, etc.) fit better with a dedicated **agent token** and the agent’s autonomy policy (`approval` / `supervised` / `autonomous`). Humans act as themselves; agent proposal rules apply to agent tokens.

      "url": "https://api.stellary.co/mcp",
      "headers": {
        "Authorization": "Bearer ${env:STELLARY_TOKEN}"
      }
    }
  }
}

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