Skip to main content

Connect your client

The Honeybase MCP server is a remote, OAuth-protected endpoint. There is no API key to paste — see OAuth, not an API key. What you tell each client is simply the URL:

https://app.honeybase.ai/api/mcp

(Use http://localhost:8080/api/mcp against a local Honeybase.)

How you supply that URL depends on whether your client speaks remote MCP natively or only stdio. Both paths end in the same OAuth consent flow.

The first-connect OAuth flow​

The first time a client reaches the endpoint, it gets a 401 whose WWW-Authenticate header points at the protected-resource metadata. From there the client, with no further configuration:

  1. Reads the metadata and finds Honeybase's authorization server.
  2. Registers itself via Dynamic Client Registration (no client ID for you to create).
  3. Opens a browser window to Honeybase.
  4. You log in and approve the requested scopes on the consent screen.
  5. The authorization server issues a token; the client stores it and retries the call.

You do this once per client; the token is reused on subsequent runs until it is revoked. If a connection later starts failing with authorization errors, have the client re-authenticate to walk the flow again.

Native remote MCP​

Clients that support remote (HTTP) MCP servers take the URL directly and handle the OAuth flow for you.

Claude Code​

Add the server with one command — --transport http selects a remote endpoint:

claude mcp add --transport http honeybase https://app.honeybase.ai/api/mcp

The next time a session uses it, Claude Code opens the browser for the OAuth consent described above. Use /mcp inside Claude Code to check the connection and, if needed, re-authenticate.

Cursor​

Add an entry to your Cursor MCP config (~/.cursor/mcp.json for all projects, or .cursor/mcp.json in a project). Cursor recognizes a remote server from its url and runs the OAuth flow:

{
  "mcpServers": {
    "honeybase": {
      "url": "https://app.honeybase.ai/api/mcp"
    }
  }
}

VS Code​

VS Code's MCP config uses a servers key and an explicit type. Add it to .vscode/mcp.json in your workspace (or your user mcp.json):

{
  "servers": {
    "honeybase": {
      "type": "http",
      "url": "https://app.honeybase.ai/api/mcp"
    }
  }
}

VS Code prompts to start the server and then runs the OAuth consent in the browser.

Claude Desktop​

Claude Desktop connects to remote servers as Connectors through its settings UI rather than a URL in a config file. Add Honeybase there as a custom connector using the endpoint URL, and approve the OAuth consent when prompted. If your build of Claude Desktop does not offer custom remote connectors, use the mcp-remote bridge below, which works from the standard claude_desktop_config.json.

Stdio-only clients: the mcp-remote bridge​

Some clients only speak MCP over stdio and cannot open an OAuth flow to a remote URL on their own. For those, the community mcp-remote bridge runs as a local stdio server and proxies to the remote endpoint, performing the OAuth (including the browser consent) on the client's behalf. It needs Node.js installed; npx fetches it on first run.

Any client that takes a command/args stdio server config accepts this shape — for example Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "honeybase": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://app.honeybase.ai/api/mcp"]
    }
  }
}

On first launch mcp-remote opens the browser for the consent flow and caches the resulting token locally for reuse.

Verifying the connection​

Once connected, ask the client to list its available tools, or use whatever tool-inspector your client offers. You should see the Honeybase tools — list_tasks, list_processes_and_workflows, and the rest. The exact set depends on the scopes you approved and your role. See Tools & skills for what they cover.

note

If nothing connects and the endpoint returns 404, the MCP server may be disabled on that deployment (mcp.enabled is off in preprod). See Availability.

If a client's exact config key differs from what is shown here, consult that client's own MCP documentation — the constant across all of them is the endpoint URL and the fact that authentication is remote OAuth, never an API key.