MCP server — Claude Code, Cursor, Codex, Continue

The @hiveship/mcp-server npm package is an MCP (Model Context Protocol) server that lets AI coding agents in your IDE read and write Hiveship issues directly, without leaving the editor. It runs locally over stdio, authenticated with an agent bearer token.

Setting up your own AI assistant (Claude Desktop, Cursor, Codex) with your personal subscription instead? See Connect an AI Client — it uses a personal access token that spans all your workspaces, with no workspace ID to configure.

npm: @hiveship/mcp-server · MIT-licensed · Node.js 20+.

Install

No installation required — run via npx:

npx @hiveship/mcp-server

Or install globally:

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

Configuration

Three environment variables, all required:

IDE setup

Claude Code

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

{
  "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 works. The command is npx -y @hiveship/mcp-server with the three env vars above.

Tools exposed to the agent

The server registers 21 tools spanning issues, projects, comments, agent sessions, sprints, labels, members, notifications, custom views, search, insights, and the audit log. The most common are below; the full list with parameters lives in the npm README.

Per-tool parameter reference (with shape, defaults, and constraints) lives in the npm package README.

Security

The MCP server is hardened for untrusted environments — it runs on the developer's machine, with credentials, talking to a public-internet API:

• SSRF prevention — HIVESHIP_API_URL is parsed and validated. Only https:// URLs are accepted (except loopback for local development); private IPv4 ranges, IPv6 link-local + ULA, IPv4-mapped IPv6, and unspecified addresses are rejected.
• HTTPS enforcement — bearer tokens never travel over plain HTTP to non-localhost hosts.
• Token format validation at startup — a token not in hsa_<agentId>_<secret> shape fails fast with a clear error.
• Rate limiting — 200 tool invocations / minute via internal token bucket. Prevents a runaway agent loop from flooding the API.
• Output sanitisation — every text response is run through a control- character + 8-bit C1 stripper, so a malicious payload in an issue body can't inject ANSI escape sequences into the agent's terminal.
• Audit attribution per tool call — every outbound API call carries X-MCP-Tool: <toolName>, and Hiveship persists the value on the matching audit row alongside the agent id, HTTP path, and response status. Super-admins can filter the audit log by MCP tool name to answer "which agent created these issues yesterday?" or "which tool fired this rogue update?" in one query. The per-issue Activity tab also surfaces the agent's typed actions (comments, session events) directly for in-context investigation.

Troubleshooting

HIVESHIP_API_TOKEN must be in format hsa_<agentId>_<secret>

You probably copied a session JWT by mistake. Generate a fresh agent token from Workspace → Agents → 🔑. It always starts with hsa_.

Authentication failed (401) at startup

The token was revoked, rotated, 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 issued more than 200 tool calls in a minute. The cap is intentional — slow down, or batch operations (use list_issues with a larger limit instead of looping get_issue).

Tools don't appear in the IDE

1. Check the IDE's MCP server logs (Claude Code: Settings → MCP servers → click the "hiveship" row).
2. Verify all three env vars are set in the IDE's MCP config — IDE-managed env vars are distinct from your shell's.
3. Try running directly from your terminal to see startup errors:
   bash

   HIVESHIP_API_URL=https://hiveship.app/api \
   HIVESHIP_API_TOKEN=hsa_... \
   HIVESHIP_WORKSPACE_ID=cl... \
   npx @hiveship/mcp-server

Next steps

• Walk through token generation if you haven't yet.
• Re-read the agent / session / capability model to pick the right tier.
• Report MCP bugs or request tools on the public repo.