Skip to main content

Connecting AI Tools to Starhive via Model Context Protocol (MCP)

Starhive exposes a Model Context Protocol (MCP) server, so any MCP-capable AI tool can ask Nova questions about your workspace's data and get answers in natural language. This guide is client-agnostic — Setup applies to every MCP client; Client examples gives exact commands for a few common ones.

What you get​

ToolWhat it does
ask_novaAsk a question about the data, types, spaces, sites, and configuration in your workspace. Returns the answer plus a conversationId.
continue_conversationSend a follow-up in an existing conversation, using that conversationId, keeping earlier context.

Nova runs as you — it only sees spaces, objects, and fields your Starhive user can already see. Connecting an AI tool never grants it more access than you already have.

Before you start​

  1. A Starhive account that's a member of the workspace you want to connect.
  2. The workspace ID (a UUID) — open the workspace in Starhive and copy it from the address bar: https://<your-starhive-host>/workspace/<workspace-id>/…
  3. An MCP client that supports the Streamable HTTP transport (not stdio — this is a remote server), and one of two ways to authenticate: OAuth 2.1 (browser sign-in) or a Personal Access Token as a Bearer token — see Authenticating below.

Endpoint​

https://api.starhive.com/mcp

Setup​

1. Tell the client which workspace to use​

Every request must identify exactly one workspace, via either (the client only needs one):

  • Query parameter (works everywhere, recommended): ?workspace=<workspace-id>
  • HTTP header starhive-workspace-id: <workspace-id> — if your client supports custom headers and you prefer a clean URL. If both are present, the header wins.

One connection = one workspace — to use several, add the server multiple times under different names, each with its own workspace ID.

2. Add the server to your client​

Point it at the endpoint above using Streamable HTTP — see Client examples below.

3. Authenticate​

The first call triggers OAuth: the client opens your browser, you sign in and approve the connection. The token is stored and refreshed automatically.

Corrected

Confirmed against application.yml (/mcp is listed in api-token-paths, with a config comment stating PATs "keep working regardless") and McpOAuthScopeRule.kt, which lets PAT-authenticated requests through unrejected — OAuth isn't the only supported method. If your client can't do browser sign-in, send a Personal Access Token as a Bearer token in the Authorization header instead; everything else in this guide (workspace identification, endpoint) works the same either way. The original migrated text claimed OAuth was the only option.

4. Verify​

Ask something only Starhive could answer, e.g.:

Using Starhive, how many spaces are in my workspace and what types do they contain?

If the answer describes your actual spaces, you're connected.

Client examples​

Claude Code​

# Add the server (name it whatever you like — "starhive" here)
claude mcp add --transport http starhive "https://api.starhive.com/mcp?workspace=<workspace-id>"

# Check it is registered
claude mcp list

Then run /mcp, pick starhive, and authenticate in the browser that opens — /mcp also shows connection status and discovered tools.

claude mcp remove starhive

Claude Desktop / JSON-configured clients​

{
  "mcpServers": {
    "starhive": {
      "type": "http",
      "url": "https://api.starhive.com/mcp?workspace=<workspace-id>"
    }
  }
}

Restart the client, then start sign-in from its MCP/connectors screen. Some clients accept headers instead, letting you drop the query parameter:

{
  "mcpServers": {
    "starhive": {
      "type": "http",
      "url": "https://api.starhive.com/mcp",
      "headers": { "starhive-workspace-id": "<workspace-id>" }
    }
  }
}

Clients with a "connect a remote MCP server" UI (e.g. Atlassian Rovo)​

Paste the full URL including the query parameter — it exists specifically for clients that can't attach custom headers:

https://api.starhive.com/mcp?workspace=<workspace-id>

Troubleshooting​

SymptomCause and fix
The starhive-workspace-id header (or ?workspace= query parameter) is required for MCP requests (400)Workspace missing from the URL — re-add with ?workspace=<workspace-id>.
Invalid starhive-workspace-id header: must be a UUID (400)The value isn't a workspace ID — copy the UUID from /workspace/<id> in the app URL, not the workspace name.
404 on every callYour user isn't a member of that workspace — check the ID, or ask an admin to add you.
401, or the client keeps asking to sign inThe token expired or lacks the MCP scope — sign out of the connection and re-authenticate.
Browser sign-in never completesThe client couldn't open a local callback URL — make sure no other MCP sign-in is in progress, then retry.
Nova did not finish within the time limitThe question was too heavy for ~55s — a partial answer may be included; ask something narrower, or continue with the returned conversationId.
Answers say data is missing that you know existsNova only sees what your user can see — check your permissions on that space.
Not authenticated: a valid personal access token and workspace are required.A stale connection ran without a resolved identity — re-authenticate, or check your PAT/OAuth token is still valid.