MCP protocol reference

fx connects to MCP servers over stdio, Streamable HTTP, or legacy HTTP+SSE. For setup commands and examples, see MCP.

Protocol compatibility

stdio and Streamable HTTP connections default to 2025-11-25 initialization and negotiate a supported version. To use MCP 2026-07-28, add "FX_MCP_PROTOCOL_VERSION": "2026-07-28" to the server's environment object.

That mode uses server/discover, stateless requests, and subscriptions/listen. It supports JSON and SSE responses and Multiple Round-Trip Requests (MRTR) for user input.

Core protocol coverage

Requests for user input

An MCP server can ask you to fill in a form or open a URL; the protocol calls this elicitation. Interactive fx collects supported form answers and asks before opening an HTTPS or loopback URL. fx does not fetch these URLs or their metadata.

fx ask supports these prompts when stdin, stdout, and stderr are terminals. --json and --quiet disable them. Otherwise, fx ask returns an input-required result. ACP advertises only the form or URL modes supported by the client session.

Tool schemas

Tool input schemas must describe an object. fx accepts JSON Schema 2020-12 and Draft 7, with limits on schema size and structure.

The server validates arguments and results against its schemas. fx checks that arguments are a JSON object within its size limit, checks response format and content, and reports tool errors.

Discovery and isolation

capability_search finds tools and loads their schemas when needed. mcp_select_tool selects a specific tool. MCP tool names include the server name to avoid collisions. Context limits bound server instructions, descriptions, search results, and schemas.

Pending and rejected project servers stay disconnected. Subagent requests stop if the parent closes or its configuration, authentication, or permissions no longer match the snapshot.

Trust and security

MCP content is external input. Resources enter model context only when read, and resource or prompt content cannot grant permissions. MCP calls follow fx's permission rules, with permissions and connection state checked again before each call.

fx status and fx doctor inspect configuration without connecting. Use fx mcp list --connect to check live connections. Connection diagnostics omit credentials, configured secrets, raw responses, and server URLs.

Stdio configuration details

Use a command array for the executable and arguments. A command string with a separate args array is also accepted.

Local servers inherit the fx process environment. Values in environment override inherited variables and must be strings; env is an alias. Servers communicate through newline-delimited JSON-RPC on stdin and stdout.

For docker run commands, fx adds a private --cidfile and removes the container after shutdown or startup failure. If you supply your own --cidfile, you handle cleanup.

Profile fields

Put server entries under mcp in ~/.fx/mcp.json. The legacy mcpServers key is also accepted; mcp takes precedence when both exist. Server names use letters, numbers, _, and -.

{
  "mcp": {
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
      "environment": {
        "LOG_LEVEL": "warn"
      }
    },
    "remote-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

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

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

Reload behavior

/mcp reload connects the new configuration before replacing the running one. If the file is invalid or a required server fails, fx keeps the previous servers. An optional server failure does not block the reload. The reload also includes approved project servers.

HTTP authentication fields

Use "type": "http" for Streamable HTTP or "type": "sse" for a legacy HTTP+SSE server. Both require a url.

Profile entries reject a literal Authorization header. Use header_env or bearer_token_env for that credential.

OAuth configuration

fx discovers the server's sign-in endpoints and refreshes saved tokens. Run fx mcp auth <name> to sign in.

All oauth fields are optional:

Without a client ID or supported metadata document, fx uses Dynamic Client Registration. If token refresh is rejected, sign in again. Temporary refresh failures preserve the saved login.

On macOS, credentials use Keychain, with a private file as fallback when no default Keychain exists. Other platforms use the file. FX_DISABLE_KEYCHAIN=1 selects file storage explicitly.

ACP does not open sign-in prompts; its host must supply authentication headers.

Project configuration limits

Project .mcp.json files use a top-level mcpServers object. Servers require approval and are always optional. Files must be regular files, not symlinks, and cannot exceed 1 MiB.

After approval, ${VAR} and ${VAR:-default} expand in commands, arguments, environment values, and HTTP headers. A missing variable without a default skips that server and produces a configuration issue. Expanded values have a separate 1 MiB total limit.

Profile strings stay literal. Use header_env or bearer_token_env to read HTTP credentials from environment variables.

Project approvals are saved per workspace. Manage them with /mcp trust. Unapproved servers stay disconnected.