MCP server
What it is
An MCP (Model Context Protocol) connection points Honeybase at an MCP server somebody else runs — a vendor's hosted server, or one your own team operates — so that the tools it advertises become available to Honeybase AI agents. It is the alternative to building a wrapper tool yourself: the vendor maintains the server, its tool definitions and its usage instructions.
Connecting is only half the setup, and the second half is the half that matters. Once the connection exists, Honeybase asks the server what it advertises and an administrator reviews each tool, approving it as read-only or mutating. Only tools a person approved are ever offered to an agent.
Connecting a server and approving its tools both require the manage integrations permission. Attaching an approved tool to an agent does not — someone who builds agents can use what was approved, but cannot connect a server or widen what is approved on one.
Before you start
Get three things from whoever runs the server:
- its endpoint URL;
- how it authenticates — no credential, a static header, or OAuth;
- and, for a header-authenticated server, the header name and value it expects.
Providers usually publish all three together. If their documentation offers a configuration snippet for a desktop AI client, the URL and the header in that snippet are the ones you want.
Decide who the connection acts as, too. A header token or an OAuth grant is one identity at the provider, shared by every agent that uses this connection, so scope it as narrowly as the provider allows.
Connecting a server sends your organization's data to a third party you chose, and Honeybase does not vet it or its operators. Tool names and descriptions from the server are shown to your agents' models, so read them before approving anything.
Setup fields
These are the fields the guided setup collects — both the Add integration form and the setup card Barry raises in chat. Additional settings live on the connection's settings page once it exists.
Connection settings
| Field | Type | Required | Secret | Notes |
|---|---|---|---|---|
name | Text | Yes | No | Display name for this connection. Agents see it too — tool names are namespaced by it, so a short, recognisable name (linear, vendor-crm) reads better than a sentence. |
serverUrl | Text | Yes | No | The MCP endpoint itself, not the provider's homepage — something like https://mcp.example.com/mcp. It must use https, and it may not carry credentials (user:password@) or a # fragment; put the credential in the authentication mode instead. Providers publish this in the page their docs call "remote MCP server", "MCP endpoint" or "connect an MCP client". |
authMode | Choice | Yes | No | How Honeybase authenticates to the server — no credential, a static header, or OAuth. The provider's documentation decides this one; see "Obtaining the credential" below. |
oauthScopes | Text | No | No | Space-separated scopes to request during the OAuth flow. Leave it empty unless the provider names specific scopes — plenty of MCP authorization servers issue a usable token with no scope request at all. OAuth mode only. |
Credentials
This integration has 3 credential options. You supply the fields for the one you pick.
No authentication
For servers that require no credential — public servers, and servers reachable only from a network you already trust. There is nothing to obtain.
No credential fields are collected for this option in the guided setup.
Static auth headers
For servers that authenticate with a static header, which is how most vendor MCP servers work today. You add the header rows on the connection rather than here, because their names are the provider's to choose and cannot be listed in advance.
No credential fields are collected for this option in the guided setup.
OAuth
For servers that publish an OAuth authorization server, which the MCP specification's authorization flow uses. You do not type a credential: save the connection, choose Connect, and approve the provider's consent screen in your browser. The two fields below are the fallback for authorization servers that do not register clients automatically.
| Field | Type | Required | Secret | Notes |
|---|---|---|---|---|
oauthClientId | Text | No | No | Only needed when the authorization server does not support dynamic client registration. Register Honeybase as an OAuth client in the provider's console and paste the client ID it issued. It is stored and displayed in the clear on purpose, so you can check it against what you registered. |
oauthClientSecret | Password | No | Yes | The client secret issued alongside that client ID, from the same registration screen. Leave both blank when the authorization server supports dynamic client registration — Honeybase then registers itself and no credential passes through your hands. Stored in the secret store: once saved it is masked and cannot be read back, only replaced. |
The guided setup does not ask for the authentication headers. Open the connection on the Integrations page to change them.
Obtaining the credential
No authentication
Nothing to obtain. Use it for public servers and for servers whose access is already controlled by the network they sit on.
A static header
Most vendor MCP servers authenticate with one header — usually Authorization with a
Bearer token, sometimes a vendor-specific name such as X-Api-Key. The token is
issued in the provider's own console, normally in the same place as its REST API keys:
look under Settings → API keys, Developer → Tokens, or whatever page the
provider's MCP documentation links to. Honeybase cannot mint it for you.
Add the rows under Auth headers, one name and one value per row. Values go to the secret store and are masked from then on. Editing a header's name clears its value, so retype the token if you rename a header.
A few names belong to the protocol and are refused rather than sent: Accept,
Content-Type, Content-Length, Connection, Host, MCP-Protocol-Version,
Mcp-Session-Id and Transfer-Encoding. The editor marks them as reserved.
OAuth
Choose this when the server answers unauthenticated requests with an OAuth challenge — the provider's documentation will talk about signing in rather than pasting a token. There is usually nothing to obtain by hand. Save the connection, choose Connect, and approve the consent screen the provider shows; Honeybase finds the authorization server the MCP server nominates and registers itself with it.
Only when that authorization server does not register clients automatically do you need credentials of your own. Register an OAuth client in the provider's console, then open Advanced: paste client credentials and paste the client ID and secret it issued. Pasted credentials take precedence over automatic registration.
If the grant is later revoked or expires, the connection reports that it is not authenticated and its tools stop working. Reconnect on the connection restores it in one step; nothing has to be retyped.
Approving tools
Test Connection checks the URL and credentials before you commit to them. Once the connection is saved, Refresh tools asks the server what it offers and lists the result under Advertised tools.
Every tool arrives unapproved and invisible to agents. Expand one with Details to read the description and input schema the server actually sent, then decide:
- Approve as read-only — for tools that only read. Agents run these without asking.
- Approve as mutating — for anything that writes, sends, deletes or spends. Agents stop and ask a person before each call.
- Revoke — takes a tool back out of service without touching the rest of the connection.
MCP gives a server no trustworthy way to declare which of the two a tool is, so the tier is yours to assign, and it is what every later agent call rests on. When in doubt, approve as mutating.
One consequence is worth knowing before you build. A mutating tool asks permission by default, and an agent holding any ask-permission tool cannot be released or used inside an AI node. That is the intended safety default: if such an agent has to run unattended, someone must deliberately change that specific tool to run automatically.
AI tier suggestions
Suggest tiers with AI asks an enabled AI connection in your organization to classify selected tools, or all Pending and Drift tools when none are selected. Choose the connection and model, then run a batch of up to 20 tools. Tool names, descriptions, schemas and annotations are sent to that provider; connection URLs and credentials are excluded. The chosen connection pays for the model requests.
Before you run, the dialog shows a Budget: in credits for Honeybase AI, in US dollars for your own AI connection. It starts at the batch's worst case, the full prompt (every byte counted as a token) plus the maximum answer for every tool at the model's list price, so real spend is usually far lower. Before each tool, the run checks that the spend so far, the worst case of requests still running and that tool's worst case fit the budget. When they no longer fit, requests already running finish, the remaining tools stay unsuggested, and the page says how many were suggested. When the model has no list price, the budget is a maximum number of tools instead. When Honeybase AI credits run out, the run stops the same way.
Progress appears in the tools section. Cancel stops tools still in the queue; requests already started may finish and save their suggestions. A failed request shows Could not classify for that tool while the rest continue. Invalid or uncertain model output produces a conservative mutating suggestion.
Suggestions survive reloads and are discarded when a definition changes. They never approve tools or alter an existing approval. Review each reason and definition, then explicitly choose Approve with suggested tiers to approve the selection. AI suggestions need verification, including when a server claims a tool is read-only. Suggesting and approving both require manage integrations.
The connection's History records every approval, revocation and drift of its tools. When a tool had a current AI suggestion, the entry and the connection's byline say so, for example "suggested by AI (gpt-5-mini)". The entry also names the AI connection, who requested the suggestion, and whether the approved tier matched it or overrode it. This applies however the approval is made: in the app, through the API or by any other channel.
Calling a tool from a workflow
Add an MCP tool node, select the connection and an approved tool, then enter its
arguments as a JSON object. String values can reference upstream results with
{{ }} expressions. The node calls the tool using the connection's organization
credential, including when you test it in the editor.
Quoted whole expressions such as "{{ Input.result.name }}" send text. Unquoted
expressions such as {"count": {{ Input.result.count }}} keep the value's JSON
type; a returned string stays a string even when it looks like JSON. Return an
object or array directly when the tool needs one. Quoted null/undefined send the
text NULL; unquoted null/undefined send JSON null.
Quotes, backslashes and newlines in upstream text stay inside that argument.
Returned {{ }}-like text is data, not another expression. A malformed template
or a key expression colliding with another key fails the node before the tool is called.
Both read-only and mutating tools can run in a workflow. The workflow author fixes
the call and releases the workflow; it does not ask for approval on each run.
Downstream nodes can read structured output through {{ MCP_tool.result.json }}
and text through {{ MCP_tool.result.text }}. Fail on tool error controls
whether a tool-reported error stops the node. An unapproved, drifted, disabled or
unauthenticated connection always fails, as does an exhausted call budget.
Keeping definitions honest
Honeybase records the exact definition of a tool at the moment you approve it and compares against that record on every re-sync and before every call. If the server later changes an approved tool's name, description or input schema, that tool is disabled, your administrators are notified, and it stays disabled until somebody reviews the change and approves it again.
Newly advertised tools appear unapproved rather than being adopted, so a server cannot widen what your agents can do on its own. Agents are always given the definition that was reviewed, never whatever the server happens to advertise at the moment of the call.
Connections re-sync roughly every 15 minutes. Refresh tools does it immediately.
Limits
- A call to the server gives up after 30 seconds.
- Honeybase reads up to 500 tools from one connection.
- Across an organization, agents, workflow nodes and Barry share 60 outbound tool calls per minute, 4 at a time. Tool descriptions and schemas are also capped, which is worth knowing if a server ships unusually large ones.
- Only the tools half of MCP is used. Resources, prompts and server-initiated requests such as sampling and elicitation are not supported, so a server that offers only those has nothing to connect.
What is stored, and what is sent
The server URL, the authentication mode and the OAuth scopes are ordinary configuration and stay readable to administrators. Header values, the OAuth client secret and the access and refresh tokens go to the secret store: they never come back to the browser, never reach workflow JavaScript, and never enter a model's context. Reading a connection returns its secrets masked — there is no way to read one back, so replace rather than recover.
Outbound calls are audited. Each records the organization, the connection, the tool name, the run and the outcome (including the process and node for workflow calls), together with a hash of the call's arguments rather than the arguments themselves.