@hiveship/mcp-server

@hiveship/mcp-server

MCP (Model Context Protocol) server that lets AI coding agents — Claude Code, Cursor, Codex, Continue, and any other MCP-compatible IDE — read from and write to a Hiveship workspace.

Hiveship is an agent-first issue tracker designed for engineering teams using AI coding agents. With this MCP server, your agent can list projects, view and update issues, leave comments, post structured activity events, and search across the workspace — all without leaving its IDE.

Installation

No installation required — run via npx:

npx @hiveship/mcp-server

Or install globally:

npm install -g @hiveship/mcp-server
hiveship-mcp

Requires Node.js 20 or later.

Configuration

The server is configured via three environment variables:

Variable	Required	Description
HIVESHIP_API_URL	Yes	Base URL of the Hiveship API. Production: https://hiveship.app/api. Self-hosted: your own URL. Plain http:// is rejected for non-localhost hosts.
HIVESHIP_API_TOKEN	Yes	Bearer token. Either an agent token (hsa_<agentId>_<secret>) for automation, or a Personal Access Token (hsp_<userId>_<secret>) so your own AI assistant sees what your user sees.
HIVESHIP_WORKSPACE_ID	Mixed	Default workspace ID for tools that operate against a single workspace. Required for agent tokens (hsa_) and workspace-scoped PATs. Optional for spanning PATs (hsp_ issued via POST /me/api-tokens) — your AI will discover workspaces via the list_workspaces tool and pass workspaceId per call.
HIVESHIP_WEB_URL	No	Base URL of the Hiveship web app, used to emit clickable deep links in tool outputs (e.g. https://hiveship.app/app/<ws>/<project>/<issue>). Defaults to a value derived from HIVESHIP_API_URL — in production the /api suffix is swapped for the /app SPA basepath (https://hiveship.app/api → https://hiveship.app/app; the web app is served under /app, so the bare origin 404s), and on localhost:3001 the port swaps to :5173 (dev server, no basepath). Must be set explicitly for self-hosted topologies where the heuristic can't infer the web location, including: (a) API on its own subdomain (api.example.com while the web app lives on app.example.com), and (b) versioned API paths like /api/v2. In both cases the derived value would silently point at the wrong place and deep links would 404 in the browser.

Optional config files

Environment variables are not the only input. Two optional JSON files hold preferences, with env → project file → user file → default precedence:

• ~/.hiveship/config.json — this machine
• .hiveship.json — this repo, safe to commit. Found by walking up from the working directory to the nearest one, stopping at the repo root.

Keys:

• defaultWorkspaceId — fills workspaceId on every workspace-scoped tool
• defaultProjectId — fills projectId on the tools that take one, so you can drop the argument
• verbosity — compact drops deep-link templates and "use page: N" nudges from list output
• apiUrl / webUrl — for self-hosted setups

Saving is non-destructive: keys this version does not recognise are preserved, one bad value costs only that key, and a config file that stopped parsing is copied aside rather than replaced.

Never put your API token in these files. It is env-only by design, and the server will not read it from disk — a project config is meant to be committed.

On first run the server asks your AI client to offer setup, and the configure tool saves your answers. Decline once and it stops asking.

Generating an API token

Pick the right token type for your use case:

Agent token (hsa_…) — for coding agents and automation that act as an agent. The agent is a first-class workspace identity with its own activity feed and capability scope.

• Open your Hiveship workspace.
• Navigate to Agents in the sidebar.
• Click Register agent, give it a name, choose a provider (e.g. Claude Code).
• Copy the token shown — it's only displayed once. Store it in your IDE's MCP config (see below).

Personal Access Token (hsp_…) — for your own AI assistant (Claude Desktop, etc.) so it queries Hiveship as you, with exactly the permissions and visibility your user account has. Two flavors:

• Spanning PAT — operates across every workspace you're a member of. Recommended for AI clients. One token, one MCP server entry, all your workspaces. Your AI uses the list_workspaces tool to discover ids and passes them per-call. Generated from Settings → Personal access tokens → Spanning (capped at 5 active per user).
• Scoped PAT — locked to one workspace at issuance. Useful for integrations that should only ever talk to one workspace (CI in a specific team, an isolated environment). Generated from a workspace's Settings → API tokens page.

To generate a spanning PAT for Claude Desktop:

• Open your Hiveship account settings (any workspace).
• Navigate to Settings → Personal access tokens → Spanning.
• Click Generate token, name it (e.g. "Claude Desktop"), pick the scopes you want (read:issues, write:issues, etc.).
• Copy the token — shown only once.
• Set it as HIVESHIP_API_TOKEN and omit HIVESHIP_WORKSPACE_ID in your IDE's MCP config. Your AI will call list_workspaces to discover the rest.

Membership is re-checked at every call. Spanning PATs only authenticate against workspaces you're currently a member of. The moment you leave a workspace, the token stops working there — even if you haven't manually revoked the token. Revocation propagates instantly.

IDE Setup

Claude Code

Add to your .claude/settings.json (project-level) or ~/.claude/settings.json (user-level):

{
  "mcpServers": {
    "hiveship": {
      "command": "npx",
      "args": ["-y", "@hiveship/mcp-server"],
      "env": {
        "HIVESHIP_API_URL": "https://hiveship.app/api",
        "HIVESHIP_API_TOKEN": "hsa_<your-agent-id>_<your-secret>",
        "HIVESHIP_WORKSPACE_ID": "<your-workspace-id>"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hiveship": {
      "command": "npx",
      "args": ["-y", "@hiveship/mcp-server"],
      "env": {
        "HIVESHIP_API_URL": "https://hiveship.app/api",
        "HIVESHIP_API_TOKEN": "hsa_<your-agent-id>_<your-secret>",
        "HIVESHIP_WORKSPACE_ID": "<your-workspace-id>"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.hiveship]
command = "npx"
args = ["-y", "@hiveship/mcp-server"]
env = { HIVESHIP_API_URL = "https://hiveship.app/api", HIVESHIP_API_TOKEN = "hsa_<your-agent-id>_<your-secret>", HIVESHIP_WORKSPACE_ID = "<your-workspace-id>" }

Using a Personal Access Token (hsp_…) for your own AI assistant instead of an agent? Set HIVESHIP_API_TOKEN to the hsp_… token and omit HIVESHIP_WORKSPACE_ID — a spanning PAT discovers workspaces via list_workspaces. See Generating an API token above.

VS Code + Continue

Add to .continue/config.json under experimental.modelContextProtocolServers:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@hiveship/mcp-server"],
          "env": {
            "HIVESHIP_API_URL": "https://hiveship.app/api",
            "HIVESHIP_API_TOKEN": "hsa_<your-agent-id>_<your-secret>",
            "HIVESHIP_WORKSPACE_ID": "<your-workspace-id>"
          }
        }
      }
    ]
  }
}

Other MCP clients

Any MCP-compatible client that supports stdio transport will work. The command is npx -y @hiveship/mcp-server with the three env vars above.

Tools

The server exposes ~26 tools. Every workspace-scoped tool accepts an optional workspaceId parameter (Phase 1.5) — resolves to the explicit argument first, then HIVESHIP_WORKSPACE_ID, then errors with a pointer to list_workspaces. Single-workspace setups don't need to pass it; spanning-PAT setups discover workspaces via list_workspaces and pass the chosen id per call.

list_workspaces (Phase 1.5)

Discover all Hiveship workspaces the calling user is a member of. Returns id, name, slug, plan tier, member/agent counts, and a deep link per workspace. Required for spanning PATs that don't set HIVESHIP_WORKSPACE_ID; cookie sessions also work. Workspace-scoped PATs are rejected with a "spanning PAT required" message.

Parameters: none

Example output:

Acme Engineering (acme) | plan: PRO | 12 members, 3 agents (id: ws-acme)
  URL: https://hiveship.app/ws-acme

Personal (personal) | plan: FREE | 1 members, 0 agents (id: ws-personal)
  URL: https://hiveship.app/ws-personal

list_projects

List all projects in a workspace, with pagination.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID; required when omitted (spanning PAT mode)
• page (number, optional, default 1)
• limit (number, optional, default 50, max 100)

Example output:

[ENG] Engineering (id: cl1abc...) — 25/100 open | Main engineering workstream
[OPS] Operations (id: cl2def...) — 5/30 open

list_issues

List issues in a project, with pagination.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required) — project CUID
• page (number, optional, default 1) — page number
• limit (number, optional, default 50, max 100) — items per page

get_issue

Get full detail for a specific issue, including description, labels, sprint, linked PRs, latest agent session, and comment/activity counts.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• issueId (string, required)

get_issue_context

Pre-work briefing for one issue in a single call: the issue core plus its most-recent comments and recent agent activity, fanned out server-side (so it replaces get_issue + list_comments + get_agent_session_activity). Use it before starting work on an issue; use get_issue for a quick look. Comments and activity are best-effort — if the token lacks read:comments or read:agents, that section renders an in-band "(unavailable — …)" note rather than failing the whole call. For a PAT, grant read:comments + read:agents in addition to read:issues to get the full briefing.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• issueId (string, required)

create_issue

Create a new issue. Server-side defaults applied when omitted: status=BACKLOG, priority=NONE.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• title (string, required, 1–500 chars)
• description (string, optional, max 50000 chars)
• status (string, optional) — override default; one of the update_issue status values
• priority (string, optional) — override default; one of the update_issue priority values

update_issue

Update one or more fields on an issue. All fields optional — pass only what changes.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• issueId (string, required)
• title (string, optional, 1–500 chars)
• description (string, optional, max 50000 chars) — omit to leave unchanged. Cannot be cleared via this tool.
• status (string, optional) — a built-in (BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE, CANCELED) or any custom workflow status from list_workflow_statuses
• priority (enum, optional) — one of URGENT, HIGH, MEDIUM, LOW, NONE
• assigneeId (string or null, optional) — pass null to unassign
• labelIds (string[], optional) — replace the label set; pass [] to clear
• storyPoints (integer or null, optional, 0–100) — pass null to clear
• dueDate (ISO datetime string or null, optional) — pass null to clear
• sprintId (string or null, optional) — add the issue to a sprint (discover ids with list_sprints); pass null to remove it from its sprint (back to the backlog)

add_comment

Post a comment on an issue.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• issueId (string, required)
• body (string, required, 1–10000 chars)

post_activity

Post a structured activity event to an active agent session. Use this to stream the agent's reasoning and actions back to the Hiveship UI in real time.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• sessionId (string, required)
• kind (enum, required) — one of thought, tool_use, elicitation, response, error
• content (object, required) — shape depends on kind:
  • thought / response → { text: string }
  • tool_use → { toolName: string, args: object, result?: any, durationMs?: number }
  • elicitation → { question: string }
  • error → { message: string, stack?: string }

Content is validated per-kind against the same Zod schema the API enforces server-side: thought.text ≤ 5 000 chars, response.text ≤ 10 000, elicitation.question ≤ 2 000, error.message ≤ 2 000 + stack ≤ 20 000, tool_use args+result ≤ 50 000 UTF-8 bytes (combined). Invalid or oversized payloads are rejected at the MCP layer before any network call.

get_my_queue

The calling agent's own work queue — issues delegated to you, oldest first (FIFO). This is the discovery step of the agent loop: poll it to find waiting work, then get_issue for detail, post_activity (with the returned sessionId) to stream progress, and link_pr when you open a PR.

Requires an agent bearer token (hsa_) — PAT-authenticated servers get a 403; use list_issues / list_agent_sessions instead.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• status (string, optional) — CSV of session statuses (QUEUED, WORKING, WAITING_INPUT, ERRORED, COMPLETED). Unknown tokens are dropped; default: QUEUED,WORKING,WAITING_INPUT
• take (integer, optional, 1–50) — max items, default 10

get_guidance

Workspace + project conventions a team configured for agents — coding standards, PR checklists, review rules, "how we write fixes here." Call this before starting work, alongside get_issue.

Pass projectId once you know which project the issue belongs to; the response concatenates project-level guidance with the workspace-level guidance. Omit it for workspace guidance only.

Requires an agent bearer token (hsa_) — PAT-authenticated servers get a 403.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, optional)

link_pr

Link a pull request to an issue — the loop-close step after opening a PR for delegated work. The PR appears on the issue detail page (and in the review queue while open), and the issue's activity stream attributes the link to the calling agent.

Idempotent create-or-refresh: re-linking an already-linked PR (same provider + number) updates the title/URL — and status/branch when provided — instead of erroring, so retries self-correct stale data. Agent tokens need a live session on the issue (write-session scope); WORKSPACE-scope tokens and PATs with write:issues pass without one.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• projectId (string, required)
• issueId (string, required)
• provider (enum, optional) — only github today; the param exists so the signature stays stable when GitLab/Azure land
• repoFullName (string, required, 1–200 chars) — owner/name form, e.g. acme/webapp
• prNumber (integer, required, positive)
• prTitle (string, required, 1–500 chars)
• prUrl (string, required) — full PR URL
• prStatus (enum, optional) — open, merged, closed. Defaults to open on a first link; omit on a re-link to leave the stored status untouched
• branchName (string, optional, max 200 chars) — head branch

search_issues

Full-text search across issues and projects in the workspace.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID
• query (string, required, 2–200 chars) — searches issue titles, issue numbers (e.g. 42 or ENG-42), and project names
• limit (number, optional, default 10, max 50)

list_labels

List all labels in the workspace, with their colors and issue counts. Use the returned IDs in update_issue.labelIds.

Parameters:

• workspaceId (string, optional) — defaults to HIVESHIP_WORKSPACE_ID

Phase 2 read tools

These broaden the surface from CRUD to "answer questions." Each is gated by a matching PAT scope — generate a token with the scope selected (see the token-generation walkthrough above). All workspace-scoped tools take the optional workspaceId.

Tool	What it does	Scope
get_workspace_insights	Agent-vs-human work share, weekly throughput, open-issue load per assignee. Optional from/to.	read:projects
get_project_insights	Burndown, velocity, cycle-time for a project (projectId).	read:projects
list_sprints	Sprints in a project; currentOnly for the active sprint.	read:projects
list_agent_sessions	Agent sessions (live + historical); status / agentId filters.	read:agents
get_agent_session_activity	Activity feed for one session (projectId, issueId, sessionId); cursor-paginated.	read:agents
list_comments	Comments on an issue (projectId, issueId).	read:comments
get_issue_context	One-call pre-work briefing: issue core + recent comments + recent agent activity (projectId, issueId).	read:issues (+ read:comments/read:agents for those sections)
list_members	Workspace roster (name, email, role).	read:members
list_notifications	Your notifications; type filter (doubles as mentions), unreadOnly.	read:notifications
list_workflow_statuses	The workspace status enum — the valid list_issues status filters.	read:projects
list_custom_views	Your saved filters for a project (projectId); shows each view's filters.	read:views
execute_custom_view	Run a saved view (viewId) — returns the issues its filters match (paginated).	read:views + read:issues
list_recent_activity	Workspace audit feed. OWNER/ADMIN only — a MEMBER's token is rejected even with the scope.	read:audit

list_issues also gained rich filters in Phase 2: statusIn / priorityIn / assigneeIds / labelIds (arrays), unassigned / assignedToAgent / currentSprint booleans, delegateType (HUMAN vs AGENT — agent-shipped work), date ranges (createdAfter … completedBefore), free-text query, and orderBy / orderDir.

Security

This server is hardened against common abuse vectors when running in untrusted environments:

• SSRF prevention — HIVESHIP_API_URL is parsed and validated. Only https:// URLs are accepted, except for loopback (localhost / 127.0.0.1 / ::1). Private IPv4 ranges (10.x, 127.x, 172.16-31.x, 192.168.x, 169.254.x AWS metadata, 0.x) are rejected. IPv6 coverage: :: unspecified, fc00::/7 ULA, fe80::/10 link-local, IPv4-mapped (::ffff:10.0.0.1 and Node's hex-normalized form ::ffff:a00:1), and IPv4-compatible (::10.0.0.1).
• HTTPS enforcement — bearer tokens are never sent over plain HTTP to non-localhost hosts.
• Token format validation — tokens that do not match either the agent format (hsa_<agentId>_<secret>) or the Personal Access Token format (hsp_<userId>_<secret>) are rejected at startup with a clear error.
• Workspace ID validation — only alphanumeric + hyphen characters allowed (no path traversal via injected slashes).
• Rate limiting — internal token bucket caps MCP tool invocations to 200/minute (in-process, per MCP server instance). Defense-in-depth against runaway tool-call loops; a single Claude turn can fan out ~8 tool calls so 200/min is comfortably above legitimate traffic. The API additionally enforces a per-token server-side rate limit (1000/5000 req/min for PATs by plan tier; agent tokens fall back to the global throttler).
• Retry with backoff — transient failures (502, 503, 429) are retried up to 2 times with jittered exponential backoff.
• Schema pre-flight on post_activity — payloads are validated against the same createAgentActivitySchema (from @hiveship/validators) the API runs server-side. Per-kind size caps (tool_use args+result ≤ 50 000 UTF-8 bytes, text fields 2 000–20 000 chars) are rejected at the MCP layer before any network call — no MCP-only constants to drift.
• Output sanitization — every text response sent to the agent is run through a control-character + 8-bit C1 stripper. ANSI escape sequences, BEL, NUL, OSC, and similar terminal control bytes are removed regardless of which API field they came from.
• API error message exposure — when the API returns an error body, the message is forwarded to the agent (capped at 200 chars). Operators of self-hosted Hiveship instances should ensure their API does not return PII or internal paths in 4xx/5xx response bodies; the API-layer NestJS defaults strip stack traces in production.
• Startup health check — the server verifies the token is valid before accepting tool calls. Bad tokens fail fast with a clear error.

The server requests an X-MCP-Tool: <toolName> header on every API call, so the Hiveship audit log knows which MCP tool triggered each request.

Troubleshooting

HIVESHIP_API_TOKEN must start with hsa_ ... or hsp_ ...

You probably copied a JWT or session token by mistake. Generate one of:

• An agent token (hsa_…) from the Agents page in your workspace, or
• A Personal Access Token (hsp_…) from Settings → Personal access tokens.

HIVESHIP_API_URL must use HTTPS for non-localhost hosts

Plain HTTP is rejected for security. Use https:// for any non-localhost URL. If you're running a self-hosted instance behind a corporate proxy, consider terminating TLS at the edge.

Authentication failed (401) at startup

The token has been revoked, expired, or doesn't match the workspace. Generate a new token and confirm it's tied to the workspace ID you've configured.

MCP local rate limit exceeded

Your agent made more than 200 requests in a minute from a single MCP server instance. The limit is intentional client-side defense against runaway tool loops — slow down, or batch operations where possible. The API also enforces an independent per-token rate limit server-side.

Tools don't appear in my IDE

• Check the MCP server logs in your IDE (Claude Code: Settings → MCP servers → click status).
• Verify all three env vars are set in the IDE's MCP config (not just your shell).
• Try running HIVESHIP_API_URL=... HIVESHIP_API_TOKEN=... HIVESHIP_WORKSPACE_ID=... npx @hiveship/mcp-server directly to see startup errors.

Development

git clone https://github.com/SorcRR/HiveShip.git
cd HiveShip/packages/mcp-server
npm install
npm run type-check
npm test
npm run build

To run the server against your local Hiveship API:

HIVESHIP_API_URL=http://localhost:3001/api \
HIVESHIP_API_TOKEN=hsa_... \
HIVESHIP_WORKSPACE_ID=cl... \
npm start

npm start runs the built dist/cli.js. The bundle has two entries: dist/cli.js is the hiveship-mcp bin, and dist/index.js is the side-effect-free library export that the hosted MCP endpoint imports (PLAT-200). The shebang is injected by tsup's banner config (not present in src/cli.ts), so tsx src/cli.ts will not be directly executable as a CLI — you need to build first or invoke with node --import=tsx src/cli.ts.

The package is part of the Hiveship monorepo. See the root README for details.

License

MIT — see LICENSE.