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, get answers in natural language, and have Nova make changes for you. This guide is client-agnostic — Setup applies to every MCP client; Client examples gives exact commands for a few common ones. To use Nova from Slack, see Starhive in Slack.

What you get

Tool	What it does
`ask_nova`	Ask a question about the data, types, spaces, sites, and configuration in your workspace. Read-only: nothing in the workspace is created, changed, or deleted. Returns the answer plus a `conversationId`.
`continue_conversation`	Send a follow-up in an existing conversation, using that `conversationId`, keeping earlier context. Read-only, like `ask_nova`.
`make_changes`	Ask Nova to create, change, move, comment on, or delete records and docs. Pass a `conversationId` to continue a conversation, or leave it out to start a new one.
`get_answer`	Wait for the answer to a request that came back with status `running`.
`cancel_conversation`	Stop a request that's still `running`. Any answer produced so far is kept.
`list_agents`	List general Nova and the custom agents shared with you, to pick one by its ID.
`list_workspaces`	List the Starhive workspaces you're a member of, to pick the one a request works in.

Reading and changing are separate tools. ask_nova and continue_conversation never change your workspace: asked for a change, Nova describes it, says it wasn't made, and points to make_changes. Before make_changes changes or deletes existing records, Nova replies with what it's about to do and waits for your answer; send that answer through make_changes with the same conversationId.

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

A Starhive account that's a member of at least one workspace.
An MCP client that supports the Streamable HTTP transport (not stdio — this is a remote server) and OAuth 2.1 sign-in in the browser — see Authenticate below.

Endpoint

https://api.starhive.com/mcp

Setup

1. Add the server to your client

Point it at the endpoint above using Streamable HTTP — see Client examples below. The same URL works for everyone; you don't need to add anything to it.

2. 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.

OAuth is the only way to sign in. A Personal Access Token is rejected by the MCP server, so a client that can't do browser sign-in can't connect.

3. 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.

Choosing a workspace

Each request works in one workspace:

You're a member of one workspace: requests use it. Nothing to set up.
You're a member of several: your AI tool calls list_workspaces and passes the chosen workspace's ID as workspace to the other tools. Ask it to use a workspace by name, e.g. "In my Acme workspace, …", or let it ask you.
A follow-up stays in the workspace its conversation started in. To work in another workspace, start a new conversation.

To tie a connection to one workspace instead, name it on the connection, and every request that doesn't pass workspace uses it:

Query parameter: https://api.starhive.com/mcp?workspace=<workspace-id>
HTTP header starhive-workspace-id: <workspace-id>, if your client supports custom headers. If both are present, the header wins.

The workspace ID is the UUID in the address bar when you open the workspace in Starhive: https://<your-starhive-host>/workspace/<workspace-id>/…

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"

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

Restart the client, then start sign-in from its MCP/connectors screen. To tie the connection to one workspace in a client that accepts headers:

{
  "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 endpoint:

https://api.starhive.com/mcp

To tie the connection to one workspace, add the query parameter, which exists for clients that can't attach custom headers: https://api.starhive.com/mcp?workspace=<workspace-id>.

Slack

Slackbot connects through the Starhive app for Slack instead of a URL. See Starhive in Slack.

Troubleshooting

Symptom	Cause and fix
`You are a member of N Starhive workspaces and this connection names none`	Your AI tool didn't say which workspace to use. Ask it to call `list_workspaces` and pick one, or tie the connection to one workspace (see Choosing a workspace).
`Workspace … is not one of yours`	The workspace ID passed isn't one you're a member of. Ask your AI tool to call `list_workspaces`, or ask an admin to add you.
`This conversation is in workspace …`	A follow-up named a different workspace than its conversation. Leave the workspace out, or start a new conversation.
`Invalid starhive-workspace-id header: must be a UUID` (400)	The value on the connection isn't a workspace ID — copy the UUID from `/workspace/<id>` in the app URL, not the workspace name.
404 on every call	The connection names a workspace your user isn't a member of — check the ID, or ask an admin to add you.
401, or the client keeps asking to sign in	The token expired or lacks the MCP scope — sign out of the connection and re-authenticate.
Browser sign-in never completes	The client couldn't open a local callback URL — make sure no other MCP sign-in is in progress, then retry.
Status `running` instead of an answer	Nova is still working. Your AI tool should call `get_answer` with the `conversationId` to wait for the answer, or `cancel_conversation` to stop it.
Status `busy`	You or your workspace already have as many Nova requests running as allowed. Wait for one to finish with `get_answer`, then retry.
Nova says a change wasn't made	The request went through `ask_nova` or `continue_conversation`, which only read. Ask your AI tool to use `make_changes` instead.
Answers say data is missing that you know exists	Nova only sees what your user can see — check your permissions on that space.
`Not authenticated: a valid OAuth access token is required.`	A stale connection ran without a resolved identity — sign out of the connection and re-authenticate.

What you get​

Before you start​

Endpoint​

Setup​

1. Add the server to your client​

2. Authenticate​

3. Verify​

Choosing a workspace​

Client examples​

Claude Code​

Claude Desktop / JSON-configured clients​

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

Slack​

Troubleshooting​