Connect a client

Connect Claude Code, Claude, Cursor, VS Code, the MCP Inspector or anything else to Halo's MCP server, with OAuth or a personal token.

When you're done, your client lists Halo's tools and whoami answers with your name. The server is at:

https://mcp.usehalo.net/mcp

Before you start

An Admin has to turn on Let members connect their own AI tools, and your role needs Use Halo AI. It's off by default: see Turn it on. If it's off, the server answers 403 agents_disabled, and the consent page shows why the organization can't be connected.

OAuth or a personal token

Both are one person in one organization, and neither can do more than that person. Keep a personal token out of chats, code and screenshots: anyone who has it acts as you. Examples here read it from HALO_MCP_TOKEN.

Claude Code

Add the server, then sign in from inside Claude Code:

claude mcp add --transport http halo https://mcp.usehalo.net/mcp

/mcp

Or use a personal token:

claude mcp add --transport http halo https://mcp.usehalo.net/mcp \
  --header "Authorization: Bearer $HALO_MCP_TOKEN"

To share the setup in a repository without the token, use a project's .mcp.json, which reads it from the environment:

{
  "mcpServers": {
    "halo": {
      "type": "http",
      "url": "https://mcp.usehalo.net/mcp",
      "headers": { "Authorization": "Bearer ${HALO_MCP_TOKEN}" }
    }
  }
}

Claude

Add Halo as a custom connector with the address above. On Free, Pro and Max you add it yourself (Free allows one custom connector). On Team and Enterprise an owner adds it for the organization, and then each member connects individually. Either way, you approve the connection on Halo's consent page.

Cursor

Put this in .cursor/mcp.json for a project, or ~/.cursor/mcp.json for all of them. Cursor signs in when the server asks.

{
  "mcpServers": {
    "halo": { "url": "https://mcp.usehalo.net/mcp" }
  }
}

{
  "mcpServers": {
    "halo": {
      "url": "https://mcp.usehalo.net/mcp",
      "headers": { "Authorization": "Bearer ${env:HALO_MCP_TOKEN}" }
    }
  }
}

VS Code

Put this in .vscode/mcp.json. With no headers, VS Code signs in when the server asks.

{
  "servers": {
    "halo": { "type": "http", "url": "https://mcp.usehalo.net/mcp" }
  }
}

To use a personal token, have VS Code prompt for it and store it rather than writing it in the file:

{
  "inputs": [
    { "type": "promptString", "id": "halo-token", "description": "Halo personal token", "password": true }
  ],
  "servers": {
    "halo": {
      "type": "http",
      "url": "https://mcp.usehalo.net/mcp",
      "headers": { "Authorization": "Bearer ${input:halo-token}" }
    }
  }
}

The MCP Inspector

The Inspector shows what the server offers, and needs a recent Node release: its README lists which. This opens it in your browser, where you can sign in with OAuth, list tools and call them:

npx @modelcontextprotocol/inspector --server-url https://mcp.usehalo.net/mcp --transport http

npx @modelcontextprotocol/inspector --cli --server-url https://mcp.usehalo.net/mcp --transport http \
  --header "Authorization: Bearer $HALO_MCP_TOKEN" \
  --method tools/call --tool-name whoami

Anything else

Any client that speaks Streamable HTTP works.

• It takes a header: send Authorization: Bearer hpat_…, and read the token from the environment.

• It signs in: Halo follows the MCP authorization spec, so a client discovers everything from the server's 401. If you're building that yourself, see Build an OAuth client.

• It's a script: see The MCP protocol for raw requests, or Build an agent for TypeScript.

Tokens go in the Authorization header only. Halo refuses ?access_token= with 400.

Check it works

Ask your client to call whoami. The answer is a sentence:

You act for Dana Reyes (dana@example.com) in Acme, as Analyst. Scopes: datasets.read, data.query, content.read. This token ends 2027-02-01T15:04:05Z.

You can see and end your connections in Account, AI tools. Admins see everyone's: see See and end connections.