Use gpf from an AI agent#

gpf ships an MCP server that exposes the case, study, market, and doctor features to an AI assistant as typed tools. Tool inputs and results follow the same public contracts as the Python API and CLI. A loaded case remains available across related tool calls in one server session.

The server is installed with every edition, including the free one. No extra package is needed, and the command is gpf mcp.

Connect a client#

The server uses the installed gpf edition. The configuration below is the same for every edition.

Nothing here has to be done by hand. An assistant that can already edit files and run commands is able to set itself up: paste this section into it and ask it to connect the gpf MCP server, and it will write its own client configuration. Restarting the client afterwards is normally required before the new tools are picked up.

The -s user scope registers the server for every project rather than only the current directory.

claude mcp add -s user gpf -- gpf mcp

Add the server to ~/.codex/config.toml:

[mcp_servers.gpf]
command = "gpf"
args = ["mcp"]

Add the server to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:

{
  "mcpServers": {
    "gpf": {
      "command": "gpf",
      "args": ["mcp"]
    }
  }
}

Clients that read the common mcpServers object, among them Claude Desktop, VS Code, Windsurf, Cline, and Zed, take the same entry. Consult the client for where its configuration file lives.

{
  "mcpServers": {
    "gpf": {
      "command": "gpf",
      "args": ["mcp"]
    }
  }
}

A client that spawns the server from a different environment than the shell must be given an absolute path to the executable, because gpf is resolved from PATH when the server is spawned. The path is reported by which gpf.

What the assistant can do with it#

The tools cover the same ground as the rest of gpf: load and save cases, solve, run the case doctor, run N-1 and other scenario studies, run optimal power flow and the market analyses built on it, take sensitivities, read and edit records, compare cases, and query a solved result with SQL.

An assistant reports its own tools, so the current list is best obtained by asking it what gpf tools it has. Every tool delegates to a documented library method, and the arguments and returned fields follow that method, so the API reference is the reference for both.

Containers#

Use the same gpf mcp command in a container. A licensed container receives GPF_LICENSE_KEY from the container platform's secret store. Do not put the key in an image layer or saved client configuration.