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

# Add an MCP server

An MCP server gives the agent extra tools, such as access to an issue tracker, a database or your
company's APIs. Once you add one, its tools appear next to the built-in ones in every chat.

## Add a server that runs on your machine

```sh
haarness mcp add files --command my-mcp-server \
  --arg=--root --arg=. --env API_TOKEN='${API_TOKEN}'
```

Give the server a name (`files`), the program to run, one `--arg` per argument and any
environment variables. Haarness prints the configuration file it wrote and whether the server
connected. If it could not start, the entry stays saved: fix the program and run
`haarness mcp reconnect files`.

## Add a remote server

```sh
haarness mcp add tracker --url https://mcp.example.com/mcp
haarness mcp add tracker --url https://mcp.example.com/mcp \
  --header 'Authorization=Bearer ${TRACKER_TOKEN}'
```

Haarness detects whether the server asks you to sign in. If it does, run:

```sh
haarness mcp auth tracker
```

Your browser opens to the provider's sign-in page; the result is stored on your machine. Use
`--no-browser` on a machine without a browser to get a link instead. `haarness mcp logout tracker`
removes the stored sign-in.

## Keep secrets out of the configuration file

Write `${NAME}` instead of the secret, as in the examples above. Haarness reads the variable when
it connects to the server, so the secret is never written to the file. `${NAME:-default}` gives a
fallback. Use single quotes so your shell does not expand it first.

The variable must be set where the Haarness workspace server started. If you set it later, run
`haarness serve --stop` and start Haarness again.

### Keep a secret in the system keychain

To avoid environment variables altogether, store the secret in your operating system's keychain
and name it with `${keychain:NAME}`:

```sh
haarness mcp secret set tracker-token      # asks for the value; it is never shown
haarness mcp add tracker --url https://mcp.example.com/mcp \
  --header 'Authorization=Bearer ${keychain:tracker-token}'
```

Haarness reads the entry only when the server starts and never logs it. It uses the macOS
Keychain, the Windows Credential Manager, or the Secret Service on Linux (through `secret-tool`,
from `libsecret-tools`). `haarness mcp secret remove tracker-token` deletes it, and
`${keychain:NAME:-fallback}` falls back when the keychain cannot be reached. In Desktop's
**Add MCP server** form, a value that looks like a secret offers to **Store in Keychain** (or the
Credential Manager or keyring) for you.

Only name keychain entries in settings you trust: the secret goes to whatever URL or program the
entry names.

## Check that it works

```sh
haarness mcp list           # each server with its connection status
haarness mcp tools files    # the tools it offers
```

In the terminal UI, `/mcp` adds, edits, enables, disables, restarts, signs in to or removes a
server.

## Use a server's resources in a message

Some servers also offer resources: documents, records or other data. Type `@` in the message box,
in Desktop or the terminal UI, and the connected servers' resources are listed after agents and
files. Pick one, and its content is read into your message when you send it.

The agent can also list and read resources itself while a server that has them is connected. Your
permission rules apply to both: a deny for that server or resource keeps it out.

## Call a tool yourself

You can call a server's tools, resources and prompts without the agent, which helps when
something is not working:

```sh
haarness mcp call files search --arguments '{"query":"needle"}'
haarness mcp resources files
haarness mcp resource-templates files
haarness mcp read files file:///workspace/README.md
haarness mcp prompts files
haarness mcp prompt files review --arguments '{"target":"src"}'
```

## Turn off one tool

The agent sees a server's tools as `mcp__<server>__<tool>`. To hide one, add it to your
configuration:

```json
{
  "tool_availability": {
    "mcp__github__delete_repository": false
  }
}
```

The model no longer sees the tool, and calls to it are refused.

## Turn a server off or remove it

```sh
haarness mcp disable files      # keep the configuration, stop connecting
haarness mcp enable files
haarness mcp reconnect files    # restart the connection
haarness mcp disconnect files   # close the connection, change nothing
haarness mcp remove files
```

`haarness mcp get files` shows a server's configuration with secrets hidden; add
`--show-secrets` to see them.

Some servers show interactive pages (MCP Apps) under their tool calls in Desktop. To get plain
text from one instead, turn off **Interactive apps** for it in Desktop's MCP settings, or set
`"apps": false` in its entry.

## Add a server to one project only

Add `--project` to `add`, `remove`, `enable`, `disable`, `get`, `auth` and `logout`. The server is
then written to the project's `haarness.json` and is used only in that project.

A project's configuration can define MCP servers that run programs on your machine. When you open
a repository you do not trust, use `haarness --disable-project-config`.

## A server stopped with "Its reply was larger than 64 MB"

A local server that sends one reply larger than 64 MB is stopped before it fills your memory, and
the agent is told not to retry. Haarness does not start it again by itself: fix what made the reply
so large, then run `haarness mcp reconnect <name>`, choose **Restart** in `/mcp`, or **Reconnect** in
Desktop's MCP settings.

## Reference

| Flag (`mcp add`) | Does |
| --- | --- |
| `--command`, `--arg`, `--env KEY=VALUE` | A server that runs locally |
| `--url`, `--header KEY=VALUE` | A remote server |
| `--oauth` / `--no-oauth` | Always or never use sign-in |
| `--oauth-scope`, `--oauth-client-id` | Sign-in details, if the server needs them |
| `--disabled` | Add it without connecting |
| `--project` | Add it to this project only |

## Related

- [Configure Haarness](https://haarness.ai/docs/cli/configuration.md)
- [Trust boundaries](https://haarness.ai/docs/security/trust-boundaries.md)