Skip to main content

​
What is MCP?

The (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:
Define servers directly in the backend config:
{
  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.

​
Server Types

The most common type. ArgentOS spawns the server as a child process and communicates over stdin/stdout.
FieldDescription
commandExecutable to run (npx, node, python, etc.)
argsArray of command-line arguments
envEnvironment variables injected into the subprocess

​
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.
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.

​
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: 
{ strictMcpConfig: false }

​
Security Considerations

  • 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.
Config file permissions: inline configs are written to temp files with mode 0600 (owner-read-write only) and cleaned up after the session.

​
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.
There is no hot-reload for MCP servers within an active session. Restart the gateway or start a new session to apply changes.