MCP server

Honeybase runs a remote Model Context Protocol (MCP) server. Point an MCP-capable AI client at it — Claude Desktop, Claude Code, Cursor, VS Code, or anything that speaks the protocol — and the client can read and act on your organization: list and update tasks, browse processes and runs, save and release workflow drafts, manage teams, schedules, availability, agents, forms and the organization database.

It is one endpoint, spoken over HTTP, protected by OAuth. This page covers what it is and how it is secured; Connect your client has the concrete configuration, and Tools & skills surveys what the client can actually do once connected.

The endpoint

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

On the hosted product the MCP server lives at /api/mcp on your Honeybase app host — https://app.honeybase.ai/api/mcp. Running locally it is http://localhost:8080/api/mcp. It is a streamable-HTTP MCP endpoint: a single POST route, no long-lived event stream and no session-deletion route (a GET or DELETE there answers 405, on purpose).

OAuth, not an API key

This is the part to get right first, because Honeybase has two authentication systems and the MCP server uses the one the GraphQL API does not.

• The GraphQL API authenticates with an organization API key — an hbk_... bearer token you create in the app and send on every request. It never expires and there is no login flow. See API → Authentication.
• The MCP server authenticates with OAuth 2.0. There is no hbk_ key involved. Your MCP client obtains a token by walking an OAuth flow against Honeybase's authorization server (Ory Hydra), and sends that token as the bearer credential.

You never paste a key into your MCP client. Instead the client registers itself and gets a token through Dynamic Client Registration (DCR, RFC 7591) plus the standard authorization-code flow — all of which the client drives automatically. The first time you connect, the client opens a browser, you log into Honeybase and approve the scopes, and the authorization server issues the token. Connect your client walks through that flow.

Automatic discovery

A compliant MCP client does not need to be told where the OAuth server is. The endpoint advertises RFC 9728 protected-resource metadata at:

GET https://app.honeybase.ai/.well-known/oauth-protected-resource
GET https://app.honeybase.ai/.well-known/oauth-protected-resource/api/mcp

That document names the resource, the authorization server, and the scopes on offer. Every unauthenticated request is answered with 401 and a WWW-Authenticate header pointing back at this metadata — which is exactly how a client bootstraps the login flow with nothing but the endpoint URL.

Identity and permissions

The token is bound to you — the Honeybase user who approved it — and to one organization. On every call the server re-checks the token, resolves your identity, and loads your role's permissions fresh from the database, so a role change or a disabled account takes effect within a short cache window rather than at some later re-login. In other words, the MCP client can never do anything you could not do in the app. Scopes (below) narrow that further; they never widen it.

Scopes

The OAuth token carries scopes, shown to you on the consent screen and enforced at the MCP boundary. A scope is a ceiling: it caps what the token may attempt, and your own role permissions cap it again underneath. A token with none of these scopes can do nothing.

Scope	What it grants
read	Read across the organization — list and inspect tasks, processes, workflows, runs, teams, schedules, availability, agents, tools, forms
write	Create and update — tasks, processes, workflow drafts, teams and their members, schedules, forms, agents and their tools — and request a workflow run, a node test run, or a role or account change that you confirm in the app (or that happens at once if you have given a standing approval there)
release	Release a workflow or agent (publish an immutable version) and pause/resume a process; also gated by the release permission on your role
orgdb.read	Read the organization database schema and run read queries against it
orgdb.write	Write rows to the organization database
orgdb.ddl	Change the organization database schema (DDL) — deliberately separate from orgdb.write, so a row-writing grant can never silently reshape tables
integrations.read	Read through your connected systems — a database, a mailbox, a spreadsheet, Drive, Slack, WhatsApp templates — on connections an administrator has enabled for assistants, and call the Agent tools and external MCP tools released to assistants; also gated by the manage-integrations permission on your role
integrations.write	Request a write to a connected system or a write-tier tool call; nothing is written until you confirm it in the app
dashboards.read	Explore what charts can query — Honeybase's own reporting views, the organization database and enabled SQL connections — run read-only queries (at most 500 rows), and read charts and dashboards; schema browsing and queries also need the manage-dashboards permission on your role
dashboards.write	Save and edit charts, create and edit dashboards and data notes, at once; deleting a chart or a dashboard is a request you confirm in the app

The organization-database, integrations.* and dashboards.* scopes are distinct capabilities from read/write/release because the blast radius — your own customer-managed data, the third-party systems you connected, and SQL over all of them — is different. None of them is implied by another: read does not reach the reporting views, and orgdb.read does not imply dashboards.read, because a dashboards query also reaches Honeybase's own data and your SQL connections. A token issued before a scope existed never gains it: reconnect the client to grant it.

Confirmation. A tool that runs something, writes to a connected system or changes someone's access does not act when the assistant calls it: it returns a link. You open it in Honeybase, read exactly what would happen — the same card Barry shows in the app — and confirm or decline, under your own session. Confirm and always allow lets that one tool skip the question from then on; revoke it any time from Barry's Standing approvals. Approve only the scopes the client actually needs.

Availability

The MCP server is gated by a server setting (mcp.enabled): on in production, off in preprod. When it is off, none of the routes above exist — the endpoint and its .well-known metadata both return 404. If you self-host and the endpoint 404s, that setting is the first thing to check.

Next

1. Connect your client — config for Claude Desktop, Claude Code, Cursor, VS Code, and the mcp-remote fallback.
2. Tools & skills — the tool categories, and the two tools that hand your coding agent the Honeybase authoring skills.