MCP

fx is an MCP client. Servers you configure are available to the interactive shell, fx ask, ACP sessions, and authorized subagents.

For transports, protocol revisions, schema handling, and isolation guarantees, see the MCP protocol reference.

Add a remote server

/mcp add --transport http adds or replaces a remote Streamable HTTP server, saves it to ~/.fx/mcp.json, and reloads MCP:

To configure headers, authentication, required startup, or other options, edit the saved entry in mcp.json. Use "type": "http" for Streamable HTTP. Use "type": "sse" only for a deprecated 2024-11-05 HTTP+SSE server. Both require a url.

{
  "mcp": {
    "remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

After editing an entry by hand, apply the change without restarting fx:

Add a local stdio server

/mcp add adds or replaces a local stdio server:

To configure one by hand, use "type": "local" or "type": "stdio". The canonical command form is an array whose first item is the executable:

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": ["node", "/absolute/path/to/server.js", "--read-only"],
      "environment": {
        "LOG_LEVEL": "warn"
      }
    }
  }
}

This compatibility form is also accepted:

{
  "mcp": {
    "filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/server.js", "--read-only"],
      "env": {
        "LOG_LEVEL": "warn"
      }
    }
  }
}

environment is canonical; env is an alias. Every value must be a string. Local servers inherit the fx process environment, then configured values override matching inherited variables. They communicate with fx using newline-delimited JSON-RPC over stdin and stdout.

For an exact docker run stdio command without --cidfile, fx injects a private container ID file and removes the owned container after shutdown or startup failure. If you supply --cidfile, cleanup remains your responsibility.

Authenticate a remote server

Choose the narrowest mechanism the server accepts:

A literal Authorization header is rejected so credentials do not become ordinary profile data.

{
  "mcp": {
    "protected": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "header_env": {
        "X-Workspace": "MCP_WORKSPACE"
      },
      "oauth": {
        "client_metadata_url": "https://example.com/fx-client.json",
        "scopes": ["tools.read", "tools.call"]
      }
    }
  }
}

Start or clear an OAuth session from the shell:

In an interactive session, fx discovers protected-resource and authorization-server metadata, validates the issuer, refreshes tokens, and answers scope challenges. It uses a Client ID Metadata Document when one is configured and advertised, and falls back to Dynamic Client Registration. Every oauth field is optional: resource, issuer, client_id, client_secret_env, client_metadata_url, and scopes.

Malformed credential entries are isolated so valid servers still work, then removed on the next successful authentication or logout. Callback issuer mismatches fail authentication instead of suggesting an unsafe override.

On macOS, OAuth credentials are stored in Keychain. If the account has no default Keychain, fx falls back to the same private 0600 credential file used on other platforms. Set FX_DISABLE_KEYCHAIN=1 to choose the portable file backend explicitly. ACP is noninteractive, so an ACP host must supply headers for a protected MCP server.

Manage servers

Run /mcp to browse server health, tools, resources, templates, and prompts. You can inspect schemas and preview resource or prompt content. Content enters the composer only after you choose Insert. The browser also supports add, remove, reload, authentication, logout, and project trust.

Direct slash commands remain available:

/mcp list
/mcp resource list <server>
/mcp resource templates <server>
/mcp resource read <server> <uri>
/mcp resource complete <server> <uri-template> <variable> [value]
/mcp prompt list <server>
/mcp prompt get <server> <name> [arguments-json]
/mcp prompt complete <server> <name> <argument> [value]
/mcp add <name> <command> [args...]
/mcp add --transport http <name> <url>
/mcp remove <name>
/mcp reload
/mcp auth <name> --open
/mcp logout <name>
/mcp trust approve <name>
/mcp trust reject <name>
/mcp trust approve-all
/mcp trust reset
/mcp path

While discovery is running, the status view reports it as in progress. Afterward it shows a health snapshot for each server, never including commands, environment values, headers, credentials, raw responses, or server URLs.

/mcp reload builds and connects the new configuration before it replaces the running one. If the file is invalid or a required server fails, fx keeps the servers you already had. If an optional server fails, the reload still goes through without it. A valid but empty profile removes every server.

Every operation is also available outside the shell as a top-level fx mcp command; see MCP management in the CLI reference. fx status and fx doctor report profile warnings and project configuration issues without starting MCP transports or opening credential storage; their JSON output marks the connection check as not_checked.

Servers with fx setup guides

These providers document fx directly, with the exact setup and authentication steps for their server:

Each provider maintains its own guide.

Profile configuration

Your private MCP profile lives at ~/.fx/mcp.json. /mcp path prints the exact profile path:

The canonical root object contains one mcp map. mcpServers is accepted as a compatibility alias, but mcp wins when both exist and fx always writes mcp. Similar unsupported keys such as MCP-Servers produce a warning and block profile mutations so fx cannot overwrite an ambiguous file.

Names passed to MCP commands must contain only letters, numbers, _, or -. Use the same form for names you add by hand, so generated tool names stay predictable.

{
  "mcp": {
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "enabled": true,
      "required": false,
      "environment": {
        "TOKEN": "value"
      }
    },
    "remote-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "enabled": true
    }
  }
}

Common server fields apply to both local and remote profile entries:

All timeout values are positive integers. restart_limit applies only to stdio servers.

Project configuration and trust

A workspace can provide Claude-compatible MCP configuration at <workspace>/.mcp.json. fx opens it as a bounded no-follow regular file and reads only the top-level mcpServers object:

{
  "mcpServers": {
    "project-local": {
      "command": "npx",
      "args": ["-y", "@example/project-server", "${PROJECT_ROOT:-.}"],
      "env": {
        "PROJECT_TOKEN": "${PROJECT_TOKEN}"
      }
    },
    "project-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "X-Workspace": "${WORKSPACE_ID}"
      }
    }
  }
}

Project servers begin as pending and stay disconnected on every surface. Interactive fx presents a trust prompt after startup. Approve or reject individual entries, approve the complete file, or clear the workspace choices:

/mcp trust approve <name>
/mcp trust reject <name>
/mcp trust approve-all
/mcp trust reset

The same actions are available as fx mcp trust ... commands. Trust is saved in your private ~/.fx/settings.json under the canonical workspace path, never in .mcp.json. Before approval, fx does not start a project process, contact a project endpoint, read an environment value, or load stored MCP credentials. fx ask reports skipped pending servers on stderr, and ACP leaves them unavailable.

After approval, ${VAR} and ${VAR:-default} expand in project commands, arguments, environment values, and HTTP headers. Missing required variables skip only the affected server and appear as configuration issues without exposing values. The file is limited to 1 MiB, and expanded values use a separate 1 MiB aggregate budget. Project servers are always optional even if they contain "required": true.

Template expansion is project-only. Profile strings remain literal; use environment, header_env, or bearer_token_env when a profile entry needs process environment values.

In native interactive and fx ask sessions, a profile entry wins a same-name project entry. ACP request entries win same-name project entries and do not inherit profile servers.

How tools reach the model

Tools are discovered when needed. capability_search searches installed skills and configured MCP tools using a query, optionally restricted to one exact server alias. Matching tool schemas load automatically within the schema budget. The agent can also use mcp_select_tool to select a tool explicitly.

Selected tools are namespaced and sanitized to avoid collisions with built-ins. Server instructions, descriptions, search results, and selected schemas are bounded by context limits.

Dynamic MCP tool calls use the same permission policy as built-in tools, re-checked immediately before transport.

Server output is untrusted input, not instructions. See Trust and security for what fx enforces, and Troubleshooting when a configured server does not appear.