Connect your AI client to Hiveship

Use Hiveship from Claude Desktop, Cursor, Codex, or any MCP-compatible client — with your own AI subscription. Ask "What did I work on last week?" or "Summarize the open issues assigned to me" and your assistant answers from live Hiveship data.

This is the conversational, bring-your-own-AI path. Your AI sees exactly what you can see: every request is checked against your workspace permissions in real time. It's distinct from the coding-agent MCP setup, which uses a workspace-scoped agent bearer token (hsa_…) for agents that act inside your IDE. Here you use a Personal Access Token (hsp_…) that works across every workspace you belong to.

Requirements

A Hiveship workspace on any plan — connecting an AI client is free on every tier.
An MCP-compatible AI client — Claude Desktop, Cursor, Codex, Continue, etc.
Node.js 20+ (the server runs locally via npx; no install step).

1. Generate a token

In the Hiveship web app, open Workspace → Settings → Connect your AI client and click Generate token. The defaults are read-only across issues, projects, and comments — enough for an assistant to answer most questions without being able to change anything. Flip on Allow write access only if you want your AI to create and edit issues, projects, and comments on your behalf.

The token is shown once. Copy it immediately — Hiveship never stores the plaintext and can't show it again. If you lose it, revoke it and generate a new one.

One token works everywhere. A Personal Access Token authenticates against every workspace you belong to; the MCP server discovers them at runtime, so you never set a workspace ID for this flow.

2. Add it to your AI client

The settings page renders a copyable, per-client snippet with your token already filled in. The snippets below use a placeholder — replace <YOUR_TOKEN> with the token you just generated.

Claude Desktop

Edit claude_desktop_config.json — on macOS at ~/Library/Application Support/Claude/, on Windows at %APPDATA%\Claude\:

claude_desktop_config.jsonjson

{
  "mcpServers": {
    "hiveship": {
      "command": "npx",
      "args": ["-y", "@hiveship/mcp-server"],
      "env": {
        "HIVESHIP_API_URL": "https://hiveship.app/api",
        "HIVESHIP_API_TOKEN": "<YOUR_TOKEN>",
        "HIVESHIP_WEB_URL": "https://hiveship.app/app"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

~/.cursor/mcp.jsonjson

{
  "mcpServers": {
    "hiveship": {
      "command": "npx",
      "args": ["-y", "@hiveship/mcp-server"],
      "env": {
        "HIVESHIP_API_URL": "https://hiveship.app/api",
        "HIVESHIP_API_TOKEN": "<YOUR_TOKEN>",
        "HIVESHIP_WEB_URL": "https://hiveship.app/app"
      }
    }
  }
}

Codex

Add to ~/.codex/config.toml:

~/.codex/config.tomltoml

[mcp_servers.hiveship]
command = "npx"
args = ["-y", "@hiveship/mcp-server"]
env = { HIVESHIP_API_URL = "https://hiveship.app/api", HIVESHIP_API_TOKEN = "<YOUR_TOKEN>", HIVESHIP_WEB_URL = "https://hiveship.app/app" }

Continue

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

.continue/config.jsonjson

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@hiveship/mcp-server"],
          "env": {
            "HIVESHIP_API_URL": "https://hiveship.app/api",
            "HIVESHIP_API_TOKEN": "<YOUR_TOKEN>",
            "HIVESHIP_WEB_URL": "https://hiveship.app/app"
          }
        }
      }
    ]
  }
}

Any other MCP client

Any client that supports the stdio transport works. The command is npx -y @hiveship/mcp-server with these environment variables:

bash

HIVESHIP_API_URL=https://hiveship.app/api \
HIVESHIP_API_TOKEN=<YOUR_TOKEN> \
HIVESHIP_WEB_URL=https://hiveship.app/app \
npx -y @hiveship/mcp-server

HIVESHIP_WEB_URL is optional — it lets the server return deep links back into the Hiveship web app. Note there is no HIVESHIP_WORKSPACE_ID: a Personal Access Token spans all your workspaces, so the server discovers them at runtime.

3. Ask your first question

Restart your AI client so it picks up the new server, then try:

"What did I work on last week?"
"What's in the current sprint?"
"Summarize the open issues assigned to me."
"Show recent activity across my workspaces."

If you have more than one workspace, ask your assistant to "list my workspaces" first — it can scope subsequent questions to whichever one you name.

What your AI can see and do

A token carries scopes — the read-only default grants read:issues, read:projects, and read:comments. You can additionally grant read access to agents, members, notifications, custom views, search, and the audit log, plus write access to issues, projects, and comments. Every API call the server makes is still re-checked against your live workspace membership and role, so a token can never exceed what your account is allowed to do.

Manage and revoke your tokens any time from Workspace → Settings → Connect your AI client. Revoking a token immediately stops any client using it.

Troubleshooting

`HIVESHIP_API_TOKEN must be in format hsp_<userId>_<secret>`

You pasted an agent bearer token (hsa_…) or a stray value. Personal Access Tokens always start with hsp_. Generate a fresh one from the settings page.

`Authentication failed (401)` at startup

The token was revoked or has expired, or you were removed from the workspace it targets. Generate a new token and re-paste the config.

Tools don't appear in the client

Confirm the client supports MCP and that you edited the right config file.
Fully restart the client — most read MCP config only at launch.

Run the command from a terminal to see startup errors: