@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 | Agent bearer token in format hsa_<agentId>_<secret>. Generate one from the Agents page in your workspace. | | HIVESHIP_WORKSPACE_ID | Yes | The workspace ID this MCP instance should operate against. Find it in the URL when viewing your workspace. |

Generating an API token

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

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>"
      }
    }
  }
}

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 9 tools:

list_projects

List all projects in the current workspace, with pagination.

Parameters:

• 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:

• 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, and latest agent session.

Parameters:

• projectId (string, required)
• issueId (string, required)

create_issue

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

Parameters:

• 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:

• 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) — one of BACKLOG, TODO, IN_PROGRESS, IN_REVIEW, DONE, CANCELED
• priority (string, 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

add_comment

Post a comment on an issue.

Parameters:

• 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:

• 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 size is capped at 100 KB per call.

search_issues

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

Parameters:

• 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: none

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 not in hsa_<agentId>_<secret> format 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 60/minute. Each tool call consumes one token; retries within a single tool call do not. Prevents runaway agent loops from flooding the API.
• Retry with backoff — transient failures (502, 503, 429) are retried up to 2 times with jittered exponential backoff.
• Content size cap — post_activity rejects payloads over 100 KB at the MCP layer before they hit the network.
• 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 be in format hsa_<agentId>_<secret>

You probably copied a JWT or session token by mistake. Generate a fresh agent token from the Agents page in your workspace — it always starts with hsa_.

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 rate limit exceeded

Your agent made more than 60 requests in a minute. The limit is intentional — slow down, or batch operations where possible.

Tools don't appear in my IDE

1. Check the MCP server logs in your IDE (Claude Code: Settings → MCP servers → click status).
2. Verify all three env vars are set in the IDE's MCP config (not just your shell).
3. 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/index.js. The shebang is injected by tsup's banner config (not present in src/index.ts), so tsx src/index.ts will not be directly executable as a CLI — you need to build first or invoke with node --import=tsx src/index.ts.

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

License

MIT — see LICENSE.