> ## Documentation Index
> Fetch the complete documentation index at: https://agnt.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom MCP servers

> Connect any MCP server and wire its tools to your agents

Beyond the connections agntdata builds and maintains, you can point a workspace
at **any MCP server** — your own internal tooling, a vendor's hosted server, or
something you run on a laptop behind a tunnel. Once connected, its tools behave
exactly like a built-in connection: you pick them per agent, they run through
the same approval rules, and they show up in the same places.

## Adding a server

Go to **Integrations → MCP servers → Add MCP server** and provide:

| Field              | Notes                                                        |
| ------------------ | ------------------------------------------------------------ |
| **Name**           | Display name. Also seeds the tool namespace.                 |
| **Server URL**     | A public `https` endpoint speaking MCP over Streamable HTTP. |
| **Authentication** | Sign in (OAuth), a bearer token, custom headers, or none.    |

We call the server immediately to fetch its tool list, so you find out right
away whether it works.

### Authentication

**Sign in (OAuth)** is the smoothest option when the server supports it. We
discover the server's authorization metadata, register agntdata as a client
automatically, and open a normal consent screen — there is nothing to configure
by hand and no client secret to manage. Tokens refresh on their own; if the
grant is ever revoked, the connection flips to **Needs auth** and one click
reconnects it.

**Bearer token** and **Custom headers** cover servers that authenticate with a
static credential. Credentials are encrypted at rest and are never readable from
the browser.

<Note>
  Only `https` endpoints that resolve to public addresses are accepted. Servers
  on localhost or a private network are unreachable from agntdata.
</Note>

## Tool names

A connected server's tools are exposed to your agents as:

```
mcp_<server>_<tool>
```

So a `create_ticket` tool on a server named `Acme internal tools` becomes
`mcp_acme_internal_tools_create_ticket`. The `mcp_` prefix is reserved, which
guarantees a custom server can never shadow a built-in `data_*`, `connection_*`
or `agnt_*` tool.

## Wiring tools to an agent

MCP tools are selected **individually**, exactly like the operations of a
built-in connection — open an agent, go to **Tools → Integrations**, and tick
the ones it should have. An agent only ever sees the tools you gave it.

You can also just ask the Agnt Wizard ("use my Acme tools to file tickets") —
custom MCP tools appear in its capability catalog alongside everything else.

## Approvals

Every MCP tool call runs through the same act / ask / always ask gate as the
rest of your integrations:

| Level          | Behavior                          |
| -------------- | --------------------------------- |
| **Act**        | Runs immediately.                 |
| **Ask**        | Pauses and asks you first.        |
| **Always ask** | Always pauses, even in autopilot. |

**Tools default to Act.** Connecting a server and giving it a credential is the
trust decision — we don't make you re-approve it on every call.

The exception is when the server tells us otherwise. MCP servers can publish
hints about what a tool does, and we honor them: a tool marked destructive
defaults to **Always ask**, so a `delete_*` on a server that labels it correctly
still stops for a human.

### Tightening specific tools

Open a server and choose **Permissions** to set the level per tool for the whole
workspace — useful for the handful that move money, delete things, or message
customers.

You can also override per agent, in the agent's **Permissions** card. A
per-agent setting wins over the workspace one, so a single agent can be trusted
with a tool everyone else has to ask about (or the reverse).

<Warning>
  A tool's name and description are supplied by the server and are visible to
  your agent, so only connect servers you trust. If you're connecting one you
  don't fully control, set its write tools to **Ask** before wiring them to an
  agent.
</Warning>

## Keeping tools in sync

We cache each server's tool list and refresh it periodically. **Refresh tools**
on the connection re-reads it immediately — use it after deploying a change to
your server. If a server is briefly unreachable, agents keep the last known tool
list rather than losing the tools mid-run.