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

# MCP servers

> Extend the agent with Model Context Protocol servers and manage tool drift safely.

Users can connect [Model Context Protocol](https://modelcontextprotocol.io)
servers to give the agent tools beyond its built-in workspace capabilities, such
as issue trackers, internal APIs, or knowledge bases.

MCP servers are configured per user under **Settings → MCP**.

## Add a server

<ResponseField name="Name" type="string" required>
  A label for the server, 1 to 80 characters.
</ResponseField>

<ResponseField name="URL" type="string" required>
  The server endpoint. Subject to the same outbound guard as model providers:
  HTTPS and a public address unless `ALLOW_PRIVATE_EGRESS` or
  `ALLOW_INSECURE_HTTP` is enabled.
</ResponseField>

<ResponseField name="Transport" type="'http' | 'sse'" default="http">
  Streamable HTTP is the current standard. Use `sse` only for older servers.
</ResponseField>

<ResponseField name="Headers" type="object">
  Optional headers for authentication, encrypted with `SETTINGS_ENCRYPTION_KEY`.
</ResponseField>

When you save a server, the control plane connects to it, lists its tools, and
records a fingerprint of the tool definitions.

<Note>
  The control plane connects to MCP servers, not the browser and not the
  workspace pod. Redirects are refused rather than followed, which prevents a
  server from redirecting the connection to an internal address.
</Note>

## Trust and tool drift

An MCP server can change its tool definitions at any time. Because tool
descriptions are instructions to the model, a changed description is a way to
influence the agent's behavior after you approved it. This attack is often
called tool poisoning or a rug pull.

r5d.chat fingerprints tool definitions when you approve a server and compares
them on later connections.

<Steps>
  <Step title="Review on first connection">
    The discovered tools and their descriptions are shown before the server is
    usable.
  </Step>

  <Step title="Trust the current definitions">
    Approving records a fingerprint of exactly those definitions.
  </Step>

  <Step title="Drift is detected automatically">
    If the definitions change later, the change is surfaced instead of being
    applied silently.
  </Step>

  <Step title="Re-approve deliberately">
    Review the new definitions and approve them explicitly to resume use.
  </Step>
</Steps>

<Warning>
  Only connect MCP servers you control or trust. A malicious server can attempt
  to steer the agent into exfiltrating workspace file contents through its own
  tool calls. Tool descriptions are model instructions, so treat adding a server
  like installing a plugin with access to your files.
</Warning>

## Operational guidance

<AccordionGroup>
  <Accordion title="Prefer scoped credentials" icon="key">
    Give each MCP server a token with the minimum scope it needs. Header values
    are decrypted for the owning user, so a broad token is a broad exposure.
  </Accordion>

  <Accordion title="Watch the tool budget" icon="list-check">
    Every connected server adds tools to each request. Large tool sets consume
    context and can degrade model tool selection. Disable servers that are not
    actively useful.
  </Accordion>

  <Accordion title="Expect latency to compound" icon="clock">
    Tool discovery happens per connection. A slow or unreachable server delays
    runs that would otherwise succeed, so remove dead servers promptly.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot add a server on a private address">
    The outbound guard blocks private destinations by default. Set
    `ALLOW_PRIVATE_EGRESS=true` if the server genuinely lives inside your
    network, and constrain the control plane with NetworkPolicy.
  </Accordion>

  <Accordion title="Server connects but exposes no tools">
    The endpoint may be a base URL rather than the MCP endpoint, or the transport
    may be wrong. Try the alternate transport and confirm the exact path with the
    server's documentation.
  </Accordion>

  <Accordion title="A previously working server now warns about changes">
    That is drift detection working. Review the new tool definitions before
    re-approving; an unexplained description change deserves scrutiny.
  </Accordion>
</AccordionGroup>