MCP

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

This page covers configuring and operating servers. For transports, protocol revisions, schema handling, and isolation guarantees, see the MCP protocol reference.

Where configuration lives

Native sessions read MCP servers only from the trusted profile at ~/.fx/mcp.json. Repository-local MCP files are never loaded or executed, so cloning a repository cannot add a server. /mcp path prints the exact file fx reads:

The root object contains one mcp map. Names passed to /mcp add must contain only letters, numbers, _, or -; using the same form for manually configured names keeps generated tool names 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
    }
  }
}

enabled is optional and defaults to true. Servers are optional by default; set "required": true when the first interactive or fx ask model request must wait for a ready server. An optional server can fail without making the rest of fx unavailable, and one-shot fx ask defers optional servers until the turn first needs MCP.

Add a local stdio server

The quickest path is /mcp add, which 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"
      }
    }
  }
}

The compatibility form below 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 environment value must be a string. Local servers communicate with fx using newline-delimited JSON-RPC over stdin and stdout.

Add a remote server

Use "type": "http" for a Streamable HTTP server. 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"
    }
  }
}

Remote entries are edited in mcp.json rather than added with /mcp add. Apply the change without restarting fx:

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:

Interactive native sessions support protected-resource and authorization-server metadata discovery, issuer validation, Client ID Metadata Documents when configured and advertised, Dynamic Client Registration fallback, refresh, scope challenges, and logout. The optional OAuth fields are resource, issuer, client_id, client_secret_env, client_metadata_url, and scopes.

On macOS, OAuth credentials are stored in Keychain. Other platforms use the private profile credential store. Existing macOS profile credentials are removed only after byte-identical Keychain publication succeeds. ACP is noninteractive, so an ACP host must supply usable headers for a protected MCP server.

Manage servers

Use the interactive MCP commands to inspect, configure, authenticate, and reload servers:

/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 remove <name>
/mcp reload
/mcp auth <name> --open
/mcp logout <name>
/mcp path

While discovery is running, the status view reports that MCP discovery is in progress. Afterward, it renders a secret-free health snapshot with configured and negotiated identity, scope, policy, transport and protocol, lifecycle and authentication state, feature counts, cache and subscription state, retry timing, discovery time, and one bounded failure. It never prints commands, environment values, headers, credentials, raw responses, or server URLs.

/mcp reload parses, connects, and evaluates a replacement before publishing it. Invalid configuration or a required-server failure retains the callable prior runtime; optional failures may publish a degraded replacement. An empty valid profile intentionally removes the profile runtime.

How tools reach the model

Tools are discovered lazily. The model calls mcp_search_tools, then mcp_select_tool, to load a matching schema, so a large catalog does not consume the context window. Selected tools are namespaced and sanitized to avoid collisions with built-ins, and 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.