Skip to main content

Relay local MCP servers through the runner

The runner can connect to MCP servers on your machine and relay their tools to FYAI. Agents see them alongside the runner's built-in tools, and the environment's allow-list and approval settings apply to them in the same way.

Use this for MCP servers that must run next to something local: an editor plugin, a desktop app, a database on your network, or a server that needs files on that machine. For MCP servers that can run anywhere, register them as a function instead (see Functions).

You need: a runner already connected to an environment (Connect a machine).

1. Add the servers to the runner's config​

Edit ~/.fyai/runner-config.yaml on the machine (create it if it doesn't exist) and add an mcp_servers block. Each key is a server name you choose.

mcp_servers:
  tickets:                      # a stdio server the runner starts
    command: npx
    args: ["-y", "@acme/tickets-mcp"]
    env:
      TICKETS_URL: https://tickets.internal.example
    deny_tools: ["delete_*"]
  docs:                         # a streamable-HTTP server that is already running
    url: http://127.0.0.1:8123/mcp
    headers:
      Authorization: Bearer <token>

Each server needs exactly one of command (stdio) or url (streamable HTTP). Server names may use letters, digits, - and single _, but not __.

KeyDefaultMeaning
command, argsProgram to start, and its arguments.
env{}Extra environment variables for a stdio server.
inherit_envfalseWhen false, the server gets a minimal environment plus env, so your own environment variables don't reach third-party code.
cwdWorking directory for a stdio server.
url, headersEndpoint and request headers for a streamable-HTTP server.
allow_toolsallfnmatch patterns over the server's own tool names. Only matching tools are relayed.
deny_tools[]Patterns of tools never relayed. Wins over allow_tools.
call_timeout_s270Per-call limit. Keep it under 300, the most a chat tool call waits.
startup_timeout_s30How long the initial handshake may take.
enabledtrueSet false to switch a server off without deleting it.

Unknown keys are rejected, so a misspelt deny_tools stops the runner with an error rather than being ignored.

2. Restart the runner​

Restart the service (or stop and start the foreground runner). The runner starts stdio servers, connects to HTTP ones and keeps them up. A server that isn't available yet, such as an editor that isn't open, is retried every 30 seconds (mcp_retry_interval_s). Its tools are announced as soon as it connects, without the runner reconnecting.

Logs from stdio servers go to ~/.fyai/logs/mcp-<server>.log.

3. Allow the tools on the environment​

Relayed tools are named <server>__<tool>, for example tickets__search_tickets. Characters outside A-Z a-z 0-9 _ - become _.

  1. Open the environment under Platform → Environments.
  2. Under Tool Access, tick each server__tool agents may use. (If the environment exposes all runner tools, they're already exposed.) If they aren't in the checklist, the runner isn't announcing them because they aren't allowed yet; follow the steps for adding an unlisted tool in Control what an environment's tools can do.
  3. Optionally tick the riskier ones under Approval Requirements.
  4. Select Save, then restart the runner so it receives the new allow-list.

4. Use them​

Any agent whose agent or team Execution Environment is this environment now has the relayed tools. Start a new chat so the agent picks them up.

Limitations​

  • Tools only. MCP resources, prompts, sampling and roots aren't relayed.
  • Image and audio results are described in text (type and size) rather than passed through.
  • Stdio and streamable HTTP are supported. The older HTTP+SSE transport isn't.
  • A relayed tool name longer than 64 characters, or one that clashes with another tool after character replacement, is skipped with a warning in the runner log. A relayed tool can't replace a built-in tool of the same name.