FC MCP Server

An MCP server, built on FastMCP, that exposes FC operations as MCP tools. Under the hood every tool shells out to fc-client, so an AI agent can lock/unlock resources, query status, run console/ssh/power commands, and drive image deploy/flash workflows.

Architecture

The server is plugin based. mcp_server.py creates the FastMCP instance, loads the internal plugin, then auto-discovers external plugins.

fc_mcp/
  mcp_server.py                # entry point (fc-mcp), transport handling
  mcp_base.py                  # MCPPlugin base class + shared helpers
  mcp_plugins/
    internal/fc_mcp.py         # core fc-client operations (always loaded)
    external/
      uuu_bcu_mcp.py           # UUU/BCU flashing tools (sample external plugin)
      uboot_mcp.py             # U-Boot console deploy tools: predeploy / uri / livedeploy (sample)
      deploy_recommender_mcp.py# deploy method recommender (entry point)

Any *_mcp.py file placed under mcp_plugins/external/ that exposes a Plugin class is discovered and loaded automatically at startup.

Installation

From the repository root:

python setup.py install fc-mcp

This installs the fc-mcp console entry point. Requires Python >= 3.10 and fastmcp >= 2.3 (needed for the Streamable HTTP transport).

Starting the server

The server supports two transports. stdio is the default and is what a local client (for example fc-agent, which launches the server as a subprocess) uses. Streamable HTTP runs the server as a standalone HTTP service so remote / third-party MCP clients can connect.

stdio (default)

fc-mcp

The client is responsible for spawning the process and talking JSON-RPC over stdin/stdout.

Streamable HTTP

# Local only (default host 127.0.0.1, port 8000, path /mcp)
fc-mcp --transport http

# Expose to the network
fc-mcp --transport http --host 0.0.0.0 --port 8000 --path /mcp

Clients then connect to http://<host>:<port><path>, e.g. http://127.0.0.1:8000/mcp.

Options

Every flag has a matching environment variable, so the server can be configured in containers/services without CLI arguments. CLI flags take precedence.

Example using environment variables:

export FC_MCP_TRANSPORT=http
export FC_MCP_HOST=0.0.0.0
export FC_MCP_PORT=9000
fc-mcp
# -> http://0.0.0.0:9000/mcp

Working directory

By default the server runs in whatever directory the launching process is in (for stdio this is the MCP client's working directory). Set FC_MCP_WORKDIR to force a specific working directory. This is where generated artifacts (for example flash/U-Boot helper scripts) are written.

• The directory is created automatically (including parent directories) if it does not exist.
• ~ and $VAR are expanded, so a shared config works per user. For shell configs prefer $HOME/... (the shell expands it at assignment); the server also expands ~/$VAR itself as a fallback, so both resolve to the running user's home directory.
• If the directory cannot be created or entered (permissions, path is a file), a warning is printed and the current directory is kept, so startup is never blocked.

# Any of these resolve to the running user's home-based directory:
export FC_MCP_WORKDIR="$HOME/fc_mcp_work"   # recommended (shell expands $HOME)
export FC_MCP_WORKDIR="~/fc_mcp_work"        # expanded by the server
fc-mcp

Authentication (HTTP transport)

By default the HTTP endpoint is unauthenticated — anyone who can reach http://<host>:<port><path> can invoke every tool. When exposing the server on a network (--host 0.0.0.0), enable static Bearer-token auth by setting the FC_MCP_AUTH_TOKEN environment variable:

export FC_MCP_TRANSPORT=http
export FC_MCP_HOST=0.0.0.0
export FC_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
fc-mcp

Behavior:

• If FC_MCP_AUTH_TOKEN is unset or empty, the server runs without auth (backward compatible).
• If set, every request must include Authorization: Bearer <token>; otherwise the server responds with 401 Unauthorized.
• The token is only enforced for HTTP transport. stdio transport ignores it.

The token is intentionally read only from an environment variable, not from a CLI flag: command-line arguments are visible to other local users via ps / /proc/<pid>/cmdline (and leak into shell history), whereas /proc/<pid>/environ is readable only by the process owner and root.

Client config with a Bearer token:

{
  "mcpServers": {
    "fc": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Connecting a third-party MCP client

For HTTP transport, point the client at the server URL. A typical MCP client config entry looks like:

{
  "mcpServers": {
    "fc": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

For stdio transport, configure the client to launch the process instead:

{
  "mcpServers": {
    "fc": {
      "command": "fc-mcp"
    }
  }
}

Available tools

Grouped by purpose (see the plugin sources for full signatures):

• Resource management (mcp_plugins/internal/fc_mcp.py): lock, unlock, status, cluster_info, all_locks, advanced_features, get_console_names, set_comment.
• Command execution (mcp_plugins/internal/fc_mcp.py): get_fc_command (build a command string), fc_command (run or return ssh/console/power/scp/rsync commands).
• Deploy recommender (mcp_plugins/external/deploy_recommender_mcp.py): recommend_deploy_method — the ENTRY POINT for any deploy/burn/flash request.
• Deploy / flash (mcp_plugins/external/uuu_bcu_mcp.py): boot_mode_switch, flash_usb_boot_nexus, flash_usb_boot_uri, flash_non_usb_boot_uri.
• U-Boot console deploy (mcp_plugins/external/uboot_mcp.py): get_board_server_ip, get_uboot_config_uri, get_uboot_config_nexus, flash_livedeploy (universal fallback deploy, always available), list_available_boards.

Deploy workflow

There are three deploy methods, all of which generate an executable script (returned as script_path) that doubles as an execution record:

The individual deploy tools are low-level executors. Do NOT call them directly. Instead follow this deterministic workflow:

1. Call advanced_features to get has_predeploy / has_uuu.
2. Call recommend_deploy_method with those capabilities plus the user-provided params (Nexus release_build_plan + build_number for coarse-grained, OR *_uri for fine-grained).
3. Call ONLY the tool named in recommended.next_tool, using recommended.next_tool_args.

Decision matrix

Coarse-grained (Nexus build specified):

Fine-grained (URIs specified):

Extending with plugins

Add a new *_mcp.py file under mcp_plugins/external/ that defines a Plugin class subclassing MCPPlugin and implementing register_tools():

from fc_mcp.mcp_base import MCPPlugin


class Plugin(MCPPlugin):
    def register_tools(self):
        @self.mcp.tool()
        def my_tool(resource_id: str) -> dict:
            """Describe what the tool does for the agent."""
            ...
            return {"success": True}

The file is picked up automatically the next time the server starts.