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

# MCP Integration

> Connect to MCP servers to extend ArgentOS with external tools and data sources. Configure stdio and HTTP servers with filtering and security controls.

## What is MCP?

The <Tooltip tip="Model Context Protocol — an open standard that lets AI agents communicate with external tool servers over a lightweight JSON-RPC transport.">**Model Context Protocol**</Tooltip> (MCP) is an open standard that lets AI agents communicate with external tool servers over a lightweight JSON-RPC transport. Each MCP server exposes a set of tools (and optionally resources) that the agent can call during a session. ArgentOS supports MCP natively — you define servers in your config and they become available as agent tools automatically.

## Configuration

MCP servers are configured in `~/.argentos/argent.json` under the CLI backend that will use them. There are two approaches:

<Tabs>
  <Tab title="Inline Servers">
    Define servers directly in the backend config:

    ```json5 theme={null}
    {
      agents: {
        defaults: {
          cliBackends: {
            "claude-cli": {
              command: "claude",
              mcpServers: {
                "claude-mem": {
                  command: "npx",
                  args: ["-y", "claude-mem-mcp-server"],
                  env: { CLAUDE_MEM_DB: "~/.claude-mem/claude-mem.db" }
                },
                "linear": {
                  command: "npx",
                  args: ["-y", "@anthropic/linear-mcp-server"],
                  env: { LINEAR_API_KEY: "lin_api_..." }
                }
              },
              mcpConfigArg: "--mcp-config",
              strictMcpConfigArg: "--strict-mcp-config",
              strictMcpConfig: true
            }
          }
        }
      }
    }
    ```

    ArgentOS writes the inline definitions to a temporary file at runtime and passes it to the CLI backend via the `mcpConfigArg` flag.
  </Tab>

  <Tab title="External Config File">
    Point to an existing MCP config JSON instead:

    ```json5 theme={null}
    {
      agents: {
        defaults: {
          cliBackends: {
            "claude-cli": {
              command: "claude",
              mcpConfigPath: "~/.argentos/mcp-servers.json",
              mcpConfigArg: "--mcp-config"
            }
          }
        }
      }
    }
    ```

    The external file uses the standard MCP config format:

    ```json theme={null}
    {
      "mcpServers": {
        "linear": {
          "command": "npx",
          "args": ["-y", "@anthropic/linear-mcp-server"],
          "env": { "LINEAR_API_KEY": "lin_api_..." }
        }
      }
    }
    ```

    <Info>
      When both `mcpConfigPath` and inline `mcpServers` are set, the external file takes precedence.
    </Info>
  </Tab>
</Tabs>

## Server Types

<Tabs>
  <Tab title="stdio (Local Process)">
    The most common type. ArgentOS spawns the server as a child process and communicates over stdin/stdout.

    | Field     | Description                                        |
    | --------- | -------------------------------------------------- |
    | `command` | Executable to run (`npx`, `node`, `python`, etc.)  |
    | `args`    | Array of command-line arguments                    |
    | `env`     | Environment variables injected into the subprocess |
  </Tab>

  <Tab title="HTTP (Remote Server)">
    For servers running as standalone HTTP services:

    ```json5 theme={null}
    {
      "my-remote-server": {
        type: "http",
        url: "http://localhost:8080/mcp",
        headers: { "Authorization": "Bearer tok_..." }
      }
    }
    ```
  </Tab>
</Tabs>

## Environment Variables

Environment variables defined in `env` are merged into the subprocess environment. The parent process environment is inherited, so API keys already in your shell (like `ANTHROPIC_API_KEY`) are available without re-declaring them.

<Tip>
  For sensitive values, consider using ArgentOS encrypted secrets (`argent secrets set LINEAR_API_KEY`) and referencing them in your shell profile rather than storing plaintext keys in the config file.
</Tip>

## Strict Mode

When `strictMcpConfig` is `true` (the default), ArgentOS appends the `strictMcpConfigArg` flag. This tells the CLI backend to reject unknown or malformed server entries rather than silently ignoring them. Disable it only if you need lenient parsing:

```json5 theme={null}
{ strictMcpConfig: false }
```

## Security Considerations

<Warning>
  * **Subprocess isolation**: stdio servers run as child processes with your user permissions. Only run servers you trust.
  * **Environment leakage**: the child process inherits your full shell environment. Use `clearEnv` on the CLI backend to strip sensitive variables that the MCP server should not see.
  * **Network servers**: HTTP MCP servers are reachable by anything on the network. Use localhost bindings and auth headers for any server exposing sensitive data.
</Warning>

<Info>
  **Config file permissions**: inline configs are written to temp files with mode `0600` (owner-read-write only) and cleaned up after the session.
</Info>

## Reloading Servers

MCP servers are spawned per CLI backend session. To pick up config changes:

* **Gateway restart**: `argent gateway restart` — reloads the full config including MCP definitions.
* **Config apply**: use `argent config apply` or the dashboard Config Panel to write and restart in one step.
* **New sessions only**: existing agent sessions keep their original MCP servers. New sessions launched after a config change will use the updated definitions.

<Note>
  There is no hot-reload for MCP servers within an active session. Restart the gateway or start a new session to apply changes.
</Note>