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

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

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:

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}:

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

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:

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:

{
  "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

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

Related

• Configure Haarness
• Trust boundaries