# MCP servers

> Any workspace member can register an MCP server from the Integrations tab, and agents can then be granted its tools. Agents can also propose a server the workspace does not have yet.

MCP (Model Context Protocol) servers let agents use tools hosted outside
Bolter. Unlike the other connectors, an MCP server is not one Bolter ships a
link flow for: you point Bolter at the server yourself, and any member of the
workspace can do it.

## Finding a server

The workspace's Integrations tab opens on a catalogue you can search and filter.
It lists MCP servers alongside the connectors Bolter ships a link flow for, so
tools such as Stripe, Zoom, Granola, Attio, PostHog and Sentry are already there.
So are the tools for getting a business off the ground: Cloudflare and Netlify
for hosting, Cloudflare, Namecheap and Porkbun for domains, Prisma Postgres,
PlanetScale and Upstash for data, Paddle, Polar and GoCardless for payments, Klaviyo,
MailerLite and Tally for marketing and forms, and Plain and Help Scout for
support.
Connecting one of those takes one step: the entry already carries the address
and the way that server authenticates, so you supply a credential value and
nothing else, or nothing at all when the server signs you in.

A few servers cannot register Bolter automatically. Those entries open the
registration form with the address and authentication method already filled in,
and ask you for a client id and secret you create in that tool first.

The catalogue is not a complete list of MCP servers, and is not meant to be.
The last tile in the grid, Connect any MCP server, reaches everything else: it
opens the same registration form described below, with nothing filled in.

## Registering a server

Open the form from Connect any MCP server on the catalogue (any member), or
from Register MCP server in the Connected view's New Integration picker (owners
and admins), then enter the server's name and URL and
choose how it authenticates:

- **Bearer token** for a single API token.
- **Username and password** for servers using basic authentication.
- **Custom headers** for anything else, such as an API key. Servers needing
  several headers, like an API key plus a tenant or profile selector, get a row
  per header.
- **OAuth** for servers that sign you in instead of taking a stored credential.
  Bolter opens the server's own sign in page, and stores the resulting tokens
  encrypted.
- **No authentication** for open servers.

Bolter contacts the server once to read its tool list before anything is saved,
so a wrong URL or a rejected credential fails at this point rather than later.
If you choose a stored credential but the server actually signs you in, the form
says so and offers to switch to OAuth.

### Choosing which permissions to ask for

Bolter reads the permissions to request from the server's own configuration, so
you normally leave this alone. The form has a "Set the permissions to request"
link for the two cases where reading them is not enough.

The first is a server that refuses the connection because of the permissions
asked for. Some services publish a list that includes permissions your workspace
is not entitled to, and they reject the whole sign in rather than granting the
part you can have. Entering just the permission the server needs, such as
`mcp:tools`, gets you through.

The second is a server asking for more than you want to grant. If the list it
publishes covers a product area you have no intention of connecting, you can
narrow it to what you actually want.

Write the permissions as a space separated list, exactly as the service
documents them. Your choice is remembered, so renewing the connection later asks
for the same permissions rather than falling back to what the server advertises.

The same control sits next to Re-connect on a server you already added, because
a server can start refusing the permissions it used to accept. Open it there and
the box shows what is currently being asked for. Clear the box to go back to
using whatever the server advertises.

### If the sign in service asks for a client ID

Most services register Bolter automatically. Some, including many corporate
sign in services, do not allow that. When that happens Bolter shows you a
redirect URL and asks for a client ID: create an application in that sign in
service, paste the redirect URL into it, then enter the client ID it gives you
back (and its secret, if it issued one). Bolter reuses those details whenever
the connection needs renewing.

### If the sign in service only accepts approved apps

A few services will not let any app register unless they approved it in advance,
and they keep that list themselves. Many of these accept a newer way for an app
to identify itself, where the app publishes its details at a web address instead
of registering, and Bolter uses that automatically whenever a service offers it.
Zip is one, so connecting Zip from the catalogue needs nothing from you beyond
signing in.

When a service offers neither, Bolter says so plainly and does not ask you for a
client ID, because there is no application you could create that would pass
their check. You have two ways through:

- **Connect with a refresh token you already have.** These services usually do
  allow a sign in from your own computer. Use a tool that can run an OAuth sign
  in against a localhost address, sign in to the service with it, and paste the
  client ID it used and the refresh token it received into the form Bolter opens.
  Bolter checks the token once, reads the server's tool list with it, and renews
  it from then on, so the connection keeps working after the first access token
  expires. Bolter needs the refresh token, not just an access token, for exactly
  that reason: an access token on its own stops working within hours.
- **Ask whoever runs the service** to approve your workspace's callback URL,
  which Bolter shows you so you can send it to them.

Expensify is one of these, and its catalogue card opens the registration form
with the refresh token fields already showing.

If neither works, a stored credential is the remaining option if the service
offers one.

A server connected with a refresh token can be renewed the same way: the
server's row in the Connected view has "Use a refresh token instead" next to
Re-connect, for when the token you gave Bolter stops working. Grants survive.

If connecting fails after Bolter has already checked the token (the server
refused the tool list, say), the token you pasted may no longer work on its
own: many services hand out a replacement each time one is used. Bolter keeps
that replacement for an hour, so submitting the same form again retries with
it. You do not need to sign in on your computer again unless the error says the
service refused the token itself.

## Who can register and manage a server

Any member of the workspace can register an MCP server, the same as storing a
secret. Whoever registers it manages it: they can reconnect it, refresh its tool
list, and approve grants on it, as can workspace owners and admins. Members
cannot manage a server someone else registered.

Registering a server makes it available to the whole workspace, not only to the
agent that asked for it. No agent gets access until a grant is approved.

## When an agent proposes a server

An agent that needs a server the workspace has not registered can propose one.
It supplies the name, the URL, and the NAMES of any auth headers the server
needs. It never supplies, sees, or asks for the values: you enter those.

A card appears in the chat with the server's full URL, the header names, and the
agent's reason. If the workspace has no other server on that host, the card says
so, because trusting a URL you have not seen before is the decision you are
making.

When the URL is one already in the catalogue, the card shows the provider's logo
and its catalogue description instead, and drops that first-time warning: it is
offering the same connection the Integrations tab offers, so there is no unknown
address to check. The endpoint is still shown in full, lower down. Only the URL
decides this. An agent that names a server "PostHog" while pointing somewhere
else gets the plain card with the warning, so the logo is never something a name
can borrow.

To complete it:

- **A server with header values**: type the value for each header on the card and
  complete the registration. The values go straight to Bolter encrypted; they
  never become part of the chat.
- **A server that signs you in**: the card offers a sign in instead of value
  boxes. Bolter opens the server's own sign in page and stores the resulting
  tokens.
- **A server that asked for a token but did not say where to sign in**: the card
  offers both. Sign in is the first option, and "Enter a token instead" switches
  to a value box. Two different kinds of server look identical here, so the card
  does not guess: pick whichever the server actually uses, and if the first
  choice fails you can switch to the other without starting over.

Anyone in the workspace can complete a proposal, or decline it.

Completing the registration does not give the agent access to anything. Once the
server is registered the agent asks for the specific tools it needs, and that
arrives as a separate access request you approve.

You do not have to prompt the agent after completing the card. It is told as soon
as the registration goes through, along with the list of tools the server offers,
and it asks for the ones it needs. Declining tells it too, so it stops waiting
rather than leaving the request open.

If the agent's URL is wrong, or nothing usable answers there, the agent is told
directly and no card is posted, so you are not asked to debug it.

## Grants

As with every connector, registering gives no agent access by itself (see
[Connectors overview](https://bolter.chat/help/connectors/index)). An agent requests a credential grant on the server, the
person who registered it (or an owner or admin) approves, and the grant can be
narrowed to a subset of the server's tools. A tool the server adds later is not
callable until the grant is updated to include it.

Agents can see what is registered before they hold any grant. Ask an agent
which MCP servers the workspace has connected and it can list them, with the
tools each offers, and offer to request access to the specific tools you want.
Listing is not access: nothing can be called until a grant is approved.

## Apps and scripts an agent builds

A grant covers more than the agent's own use of a server. Code the agent writes
can call the same server too, so it can build you something that uses a
connected service rather than only talking about it. That includes an app it
publishes, which keeps working after the conversation ends.

The rules do not change when the caller is code:

- The server's credentials never reach the app. Bolter attaches them, so the
  app only ever holds a token that works against Bolter.
- Only the tools you approved are callable. A tool the server offers but the
  grant does not cover is refused, exactly as it would be for the agent.
- Revoking the grant stops the app on its next call. There is no delay and no
  cache to wait out.

If you suspect an app's token has leaked, the agent can replace it, which
immediately stops anything still holding the old one. That does not remove the
app's access. To do that, revoke the grant.

## Seeing what was used

Every call through a connected MCP server is recorded: which grant, which tool,
whether it ran, and whether it was refused. Refusals are recorded alongside
successes, so the history answers what was attempted, not only what worked.

Tool names are recorded. The values passed to a tool, and whatever it sent
back, are not.

Source: https://bolter.chat/help/connectors/mcp