MCP Server

Forward exposes its read-only network-analysis tools over the Model Context Protocol (MCP). These are the same tools that Forward AI uses. Through an MCP client, an external LLM agent or IDE can trace paths, run NQE queries, and look up devices, interfaces, VLANs, VRFs, hosts, cloud objects, and vulnerabilities.

Every tool is read-only. No tool exposed over MCP can change the network, its configuration, or platform state.

Availability

The MCP server is served at /api/mcp on both SaaS and self-hosted deployments, and is enabled by default. An admin can turn it off for their organization:

• On a self-hosted deployment, an admin opens Settings → System → Org preferences, expands Experimental features, and disables the Enable MCP server toggle.
• On SaaS, contact Forward support.

While the server is off, /api/mcp returns HTTP 403 for every request. No tools are listed, and no tools run. An expired or inactive license also returns HTTP 403.

Authentication

MCP requests use the same API token as the rest of the Forward API, sent as HTTP Basic credentials:

• Username: the token's access key
• Password: the token's secret

Mint a token from Settings → Account → API tokens, or with POST /api/users/current/tokens. The token belongs to a real user and carries that user's organization and per-network permissions. An MCP client can reach only the data that its user can reach in the UI.

Form the Basic credential by Base64-encoding accessKey:secret:

echo -n 'accessKey:secret' | base64

The endpoint is stateless. It creates no session and is exempt from CSRF checks.

Client support

Clients that let you set a static Authorization header work with the MCP server. These include Cursor, Cline, VS Code, the MCP Inspector, and custom agents.

Forward does not implement the OAuth 2.1 authorization flow. Clients that require OAuth-based discovery, such as Claude Desktop and claude.ai, cannot connect.

Configuring a client

Configure your client with the streamable-HTTP endpoint and the Basic Authorization header. A typical JSON configuration looks like this:

{
    "mcpServers": {
        "forward": {
            "url": "https://<your-forward-host>/api/mcp",
            "headers": {
                "Authorization": "Basic <base64 of accessKey:secret>"
            }
        }
    }
}

Once connected, call tools/list to get the tools you can use. The available tools:

Tool	What it returns	Requires AI
get_paths	Traces packet paths through the network	No
get_device	Details for a device	No
get_interface	Details for an interface	No
get_vlan	A VLAN and the interfaces on it	No
get_vrf	A VRF, its devices, and its interfaces	No
get_host	Details for a host	No
get_cloud_object	Details for a cloud object	No
get_subnet_locations	Where a subnet is located	No
get_device_vulnerabilities	Vulnerabilities on a device, sorted by severity	No
get_vulnerability	Details for a specific CVE	No
get_network_complexity	Inventory summary: device, vendor, and type counts, plus VLANs, VRFs, and flows	No
nqe	Generates and runs an NQE query and returns a summary	Yes
generate_nqe_query	Generates an NQE query from a description without running it	Yes
search_docs	NQE documentation for syntax, functions, and the data model	Yes

New tools may be added in later releases. Your client's tool list always reflects what your deployment currently offers.

Two things narrow the list for your organization:

• Tools not included in your license do not appear.
• Tools that use AI, such as nqe, appear only when your organization has AI enabled.

The list does not account for per-network permissions. Those are checked when a tool runs, so a tool can appear in the list and still be denied for a specific network.

Calling a tool

An MCP request carries no network or snapshot context on its own. Every tool call includes:

• networkId (required): the ID of the network to run against. MCP has no tool to list networks, so you need this ID in advance.
• snapshotId (optional): a specific snapshot. When omitted, the tool uses the network's latest processed snapshot.

The call also includes the tool's own arguments. For a path trace with get_paths:

{
    "networkId": "123456",
    "srcIp": "10.1.1.10",
    "dstIp": "8.8.8.8"
}

Each tool declares a required permission. get_paths requires VIEW_PATHS, nqe and generate_nqe_query require USE_NQE, and the other tools require view access to the network. If your user does not hold the required permission on the requested network, the call returns an error and no data. A call for a network ID that has no processed snapshot you can reach also returns an error.

The result is returned as JSON text and structured content.

Limits and scope

• Read-only. Every tool only reads from the snapshot. None change the network, its configuration, or platform state.
• No discovery. No tool lists networks or snapshots. You supply the networkId.
• Result caps. Tools that can produce large output are capped. nqe reads at most 100 rows per query and returns the query, a summary, and a result key instead of the rows. search_docs returns at most two documentation chunks, and get_paths returns a single path result. The other tools return a single object or its contents.