MCP protocol reference
fx connects to MCP servers over stdio or Streamable HTTP. For setup commands and examples, see MCP.
Core MCP client scope
fx is an MCP client for tools. It does not currently implement MCP resources, prompts, completion, sampling, or roots, or the MCP Tasks, MCP Apps, Skills over MCP, Client Credentials, or Enterprise-Managed Authorization extensions. fx does not connect to legacy HTTP+SSE servers, install servers from a registry, or expose itself as an MCP server.
Protocol compatibility
| Transport | Supported versions |
|---|---|
| stdio | 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 |
| Streamable HTTP | 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26 |
fx detects each server's version, so there is nothing to configure. It asks for MCP 2026-07-28 first with server/discover. A server that doesn't answer it gets initialize with 2025-11-25 and may choose 2025-06-18 or 2025-03-26 instead.
With 2026-07-28 servers, fx uses stateless requests and subscriptions/listen. It accepts JSON and SSE responses and supports Multiple Round-Trip Requests (MRTR) for user input.
Legacy HTTP+SSE servers ("type": "sse") are not supported, and /mcp list shows them as not supported. A server that speaks only 2024-11-05 fails to connect.
Core protocol coverage
| Feature | Support |
|---|---|
| Tools | Discovery with pagination, calls, progress, and cancellation. |
| Updates | Tool list-change notifications, and subscriptions/listen with 2026-07-28 servers. |
| Elicitation | Forms and URLs that request user input. |
| Resources, prompts, and completion | Not supported. |
| Sampling and roots | Not supported. fx doesn't offer them, and answers a server's request for either with an error. |
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 shows the form, or asks before opening the URL in your browser. fx does not fetch these URLs or see what the browser shows.
fx ask asks the same way when stdin, stdout, and stderr are terminals. --json and --quiet turn this off, and then a server's request for input ends that call. ACP forwards form and URL requests to the client when the client supports them.
Tool schemas
A tool's input schema must be a JSON object with "type": "object". fx accepts JSON Schema 2020-12 and Draft 7, up to 64 levels deep, 4,096 nodes, and 256 KiB. A tool outside these limits is left out of its server's tools.
Arguments must be a JSON object of at most 1 MiB. The server validates them against its schema, and fx reports the tool errors it returns.
A tool's result can be up to 8 MiB. As with other tools, a large result in a saved conversation is stored whole for read_tool_result. Otherwise the model gets its first 64 KiB. Through fx mcp call, a structured result can be up to 16 MiB, and it goes to the command instead of the model.
Discovery and isolation
The agent reaches MCP tools through toolbox: its menu lists each server, search finds tools, open returns a server's tools or one tool's schema, and run calls a tool. MCP tool names include the server name to avoid collisions. Context limits bound server instructions, descriptions, search results, and schemas.
| Session | Available servers | Same-name entries |
|---|---|---|
Interactive fx and fx ask | Profile and approved project servers. | Profile wins. |
| ACP | Client-supplied and approved project servers; profile servers only with explicit client opt-in. | Client, then profile, then project. |
| Subagent | The servers its parent can use, checked again at each call, or the servers its agent profile lists in mcp_servers. | Inherited from the parent. |
Pending and rejected project servers stay disconnected.
In ACP, the tools of a client-supplied server are offered to the model on every turn, without a search, unless the client sets _meta.fx.alwaysLoaded to false for that server. Their schemas share the mcp_selected_schema_bytes context limit; tools past it stay available through toolbox.
Trust and security
MCP content is external input, and it cannot grant permissions. MCP calls follow fx's permission rules.
fx mcp list and fx status read configuration without connecting. Use fx mcp show <name> to connect to a server and see its status, version, and tools. fx doctor connects to each approved server the same way, each in its own fx mcp show process, and never starts an unapproved project server. Its checks run in the order of your configuration, at most one per CPU at once, at least 4 and at most 16, so servers that hang hold their places until its 5 second limit, and servers queued behind them are reported as not checked.
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 get only HOME, LOGNAME, PATH, SHELL, TERM, and USER from the fx process environment, as in the MCP SDKs, so your AI Gateway key and other variables stay with fx. Pass anything else a server needs in env, such as "GITHUB_TOKEN": "${GITHUB_TOKEN}". Values in env override inherited variables and must be strings; environment is also accepted and is used when both are present. Servers communicate through newline-delimited JSON-RPC on stdin and stdout.
Each server runs in its own process group. When fx exits, it sends each group SIGTERM without waiting; a server still running 2 seconds later gets SIGKILL, even if fx crashed.
Profile fields
Put server entries under mcpServers in ~/.fx/mcp.json. Older files that use the mcp key keep loading; don't use both keys in one file. Server names use letters, numbers, _, and -.
{
"mcpServers": {
"local-tools": {
"type": "stdio",
"command": ["npx", "-y", "@modelcontextprotocol/server-everything"],
"env": {
"LOG_LEVEL": "warn"
}
},
"remote-tools": {
"type": "http",
"url": "https://mcp.example.com/mcp"
}
}
}
| Field | Description | Default |
|---|---|---|
enabled | Set to false to keep an entry without starting it. | true |
startup_timeout_ms | How long the server may take to start. | 30000 |
operation_timeout_ms | How long a request may wait without an answer or a progress update before fx stops waiting and tells the model the server did not answer in time. Raise it for tools that run longer without reporting progress. | 300000 |
A request also ends after 10 minutes, or after operation_timeout_ms when that is longer, even while the server reports progress.
A line from a server that fx can't read, such as bytes that aren't UTF-8, doesn't count as an answer. If fx can still tell which request the line answers, for example when only its jsonrpc value is wrong, that request ends at once. Otherwise the line names no request. Over stdio, each tool call and tool list still waiting then gets 30 seconds to be answered or to report progress. Over Streamable HTTP, only the tool call or tool list on the stream that carried the event gets those 30 seconds, and other calls keep their own timers.
A call that gets neither an answer nor progress in those 30 seconds ends with a tool error, "the server's answer was malformed", and fx sends the server a cancellation.
Over Streamable HTTP, a JSON body that fx can't read ends its call at once as malformed when the response has a 2xx status. With an error status, the call ends with that HTTP failure instead.
A server that stops or fails to start is started again, up to 8 tries in a row, waiting from 1 to 30 seconds between tries. The count starts over once the server has stayed up for a minute. fx ignores required and restart_limit, and /mcp list notes an entry that sets them so you can remove them.
Reload behavior
/mcp add, /mcp remove, /mcp approve, and /mcp reject take effect right away and touch only the servers they change. A server whose configuration stays the same keeps running, along with its connection, sign-in, and calls in progress. A removed server stops, and a call still running on it ends with an error saying the MCP config changed. An added or changed server starts once its earlier process has exited, so only one copy runs at a time. A browser sign-in in progress continues unless the change removes or changes that server.
fx loads a change made outside these commands the same way, touching only the servers it changes. That includes your own edit to ~/.fx/mcp.json or .mcp.json, fx mcp add or fx mcp remove in another terminal, and an approval made in another fx window. fx checks for it when you send a prompt and when you run a /mcp command. A prompt sent while a turn is still running keeps the current servers, and the next prompt after it loads the change.
HTTP authentication fields
Use "type": "http" with a url. fx also reads "streamable-http" as http.
| Field | Description |
|---|---|
headers | Static header names and values. |
header_env | Maps header names to environment variables containing their values. |
bearer_token_env | Environment variable containing the bearer token. |
oauth | Browser sign-in configuration. |
fx reads these variables when it starts. If one is missing, /mcp list shows the server as needing it. If one holds a line break or another control character, which a header can't carry, /mcp list shows can't use $NAME and fx sends nothing to that server.
Profile entries reject a literal Authorization header, and header_env can't set one. Use bearer_token_env for that credential.
OAuth configuration
fx discovers the server's sign-in endpoints, signs in with fx mcp login <name>, and refreshes saved tokens.
All oauth fields are optional:
| Field | Description |
|---|---|
client_id | ID for a registered OAuth client. |
client_secret_env | Environment variable holding the client secret; requires client_id. |
client_metadata_url | Client ID Metadata Document URL, used when the server supports it and no client_id is set. |
callback_port | Port for localhost callbacks, from 1 to 65535. Omit to use an available port. |
resource | The protected resource to request tokens for, when it must be written differently from the server's own, such as with a trailing slash. |
scopes | An array of scopes to ask for instead of the ones the server lists. Scopes the server requests when it rejects a token still take precedence. |
Without a client ID or supported metadata document, fx uses Dynamic Client Registration. Without scopes, fx asks for the scopes the server lists or requests. If the server rejects a token refresh, the server needs a new sign-in. Temporary refresh failures keep the saved login. When several fx windows use one server, one window refreshes its sign-in at a time and the others use the login it saved. If fx can't save a new login, it says so: the login keeps working in that window, and the server needs a new sign-in after fx restarts.
Slack uses fx's own Slack app unless you set client_id. Its sign-in returns to http://localhost:3118/callback, and fx asks for the scopes the app has. Slack renews this login without the app's secret while fx uses it; after 30 days without a renewal, sign in again.
On macOS, credentials use Keychain, with the private file ~/.fx/mcp-credentials/credentials-v3.json as fallback when no default Keychain exists. Other platforms use the file. FX_DISABLE_KEYCHAIN=1 selects file storage explicitly.
ACP sessions do not open sign-in. The ACP client can supply an Authorization header for its servers.
Project configuration limits
Project .mcp.json files use a top-level mcpServers object. Servers require approval. 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 header values. A missing variable without a default skips that server, and /mcp list explains why. Expanded values have a separate 1 MiB total limit.
~/.fx/mcp.json expands variables the same way in interactive fx and fx ask. ACP sessions read profile strings as written.
Project approvals are saved per workspace. Manage them with /mcp approve and /mcp reject. Unapproved servers stay disconnected.