Skip to content
Open Garphield

Garphield for agents

An agent can build a Garphield graph from data, bind colour, size and link width to its fields, lay it out, and hand back a link that opens it in the workbench. Choose the route that matches where the agent runs:

You are Use Needs
A chat assistant with connectors (claude.ai, ChatGPT) The hosted connector at https://mcp.garphield.com/mcp Nothing installed
A coding agent or a script npx -y garphield-mcp, a local stdio MCP server and CLI Node.js 22.19 or later
A browser agent in an open Garphield tab The WebMCP tools, or window.garphield The tab
A Python user pip install garphield Python 3.10 or later
Testing the Garphield app itself Playwright and window.garphield A browser

The hosted connector, garphield-mcp and the workbench’s WebMCP tools share one set of garphield_* tool definitions, so a prompt that works on one route works on the others.

The server URL is https://mcp.garphield.com/mcp. It needs no sign-in.

  1. In claude.ai, open Customize > Connectors, select +, then Add custom connector.
  2. Name it Garphield, paste the server URL, and add it. It needs no OAuth client ID or secret.
  3. In a conversation, turn the connector on from the tools menu and ask for a graph.

On Team and Enterprise plans an owner adds the connector under Organization settings > Connectors, and members then connect it from Customize > Connectors. Free accounts can add one custom connector. Connectors added in claude.ai also appear in Claude Desktop and the mobile apps.

  1. Open chatgpt.com/plugins, select +, then Add custom MCP server.
  2. Enter a name and the server URL, including /mcp. Choose no authentication.
  3. Accept the warning about custom servers and create the plugin.

OpenAI documents custom MCP servers for Business, Enterprise and Edu workspaces on ChatGPT web, where an admin or owner may need to create the plugin. Pro accounts can connect custom servers with read and fetch permissions only, which leaves out the tools that create and change a graph.

Claude Code, Codex and Cursor can use the hosted connector too:

Terminal window
claude mcp add --transport http garphield https://mcp.garphield.com/mcp
~/.codex/config.toml
[mcp_servers.garphield]
url = "https://mcp.garphield.com/mcp"
{
"mcpServers": {
"garphield": { "url": "https://mcp.garphield.com/mcp" }
}
}

The last snippet goes in Cursor’s .cursor/mcp.json or ~/.cursor/mcp.json. For a coding agent working on files, the local server below is usually the better fit: documents stay on disk and links carry the whole graph.

  • Each graph you create is stored so its link can load it. The link is the only key: anyone who has it can open that graph.
  • A stored graph expires 30 days after its last change. To keep one, open it and use Share in Garphield, or ask for the .gph file with garphield_export.
  • A later style or layout call changes what an existing link shows.
  • No account is needed. Requests are rate limited per address and overall, and the server stores a fixed amount of new data each day. Once that is used up, changes return RATE_LIMITED until 00:00 UTC; reading, sharing and exporting text formats still work.
  • PNG export renders the graph in Cloudflare Browser Run and stores the image beside the graph.

garphield-mcp is the same set of tools as a local stdio server. Documents are .gph files on your disk, links carry the whole document in the URL and do not expire, and everything but PNG export runs offline. The server reads and writes files in its working directory; --root <dir> names another tree. It refuses to start in / or your home directory without --root, since every file there would be in reach.

Claude Code, for the current project:

Terminal window
claude mcp add garphield -- npx -y garphield-mcp

Add --scope project before -- to share it through .mcp.json.

Claude Desktop: in claude_desktop_config.json (Settings > Developer > Edit Config). Desktop starts servers in /, so --root is required:

{
"mcpServers": {
"garphield": {
"command": "npx",
"args": ["-y", "garphield-mcp", "--root", "/Users/you/graphs"]
}
}
}

Codex: in ~/.codex/config.toml, or run codex mcp add garphield -- npx -y garphield-mcp --root /Users/you/graphs. Codex may start servers in your home directory, so name the folder:

[mcp_servers.garphield]
command = "npx"
args = ["-y", "garphield-mcp", "--root", "/Users/you/graphs"]

Cursor: in .cursor/mcp.json (project) or ~/.cursor/mcp.json:

{
"mcpServers": {
"garphield": {
"command": "npx",
"args": ["-y", "garphield-mcp", "--root", "${workspaceFolder}"]
}
}
}

The same binary is a command-line tool. Each subcommand wraps the tool of the same name:

Terminal window
npx garphield-mcp create messages.csv --nodes people.csv -o team.gph
npx garphield-mcp inspect team.gph
npx garphield-mcp style team.gph --bind color=team --bind edgeWidth=messages
npx garphield-mcp share team.gph

PNG export needs playwright-core and a Chrome or Chromium browser; see the package README for setup.

Tool Does
garphield_create Builds a document from node-link JSON, CSV text or a graph file. The local server also reads file paths. Not in the workbench.
garphield_inspect Lists the fields a binding can name, the channels, the algorithms, the config and a quality grade.
garphield_style Binds channels to fields or algorithms and sets the layout mode, theme and tooltip. If any binding is invalid, nothing is written.
garphield_layout Computes and saves positions. Optional, because the browser lays out a graph without positions when it opens. Not in the workbench.
garphield_validate Checks a document the way the workbench loads it.
garphield_share Returns an app link, an embed link and an iframe snippet.
garphield_export Returns .gph, node-link JSON, GEXF, GraphML, GML or a PNG.

In hosts that support MCP Apps, garphield_share also shows the graph inline in the conversation. The agent manual has a worked example for each route, the binding rules, the error codes and the full tool schema.

Resource Contents
https://garphield.com/llms.txt The agent manual: routes, worked examples, bindings, and the command and MCP tool schemas.
https://garphield.com/llms-full.txt Every documentation page.
https://mcp.garphield.com/mcp The hosted MCP server.
window.garphield.schema() The live command schema in an open workbench.

See the Automation API for window.garphield, WebMCP and their boundaries.

The welcome dialog’s presets as commands

Section titled “The welcome dialog’s presets as commands”

The three question-led entry points on the welcome dialog are command sequences. An agent in an open workbench reproduces each by running the same commands.

Which characters hold the story together?

await garphield.run("sample.load", { id: "les_mis" });
await garphield.run("channel.bind", { channel: "size", kind: "algorithm", source: "betweenness" });

Which institutions bridge research communities?

await garphield.run("file.load", { url: "/datasets/eurosis.json" });
await garphield.run("channel.bind", { channel: "color", kind: "algorithm", source: "louvain" });
await garphield.run("channel.bind", { channel: "size", kind: "algorithm", source: "betweenness" });

How does a team form over time?

await garphield.run("sample.load", { id: "temporal-collaboration" });
await garphield.run("filter.add", { kind: "field", source: "joined" });
await garphield.run("filter.play");

The same sequences open from a link: /?preset=story-connectors, /?preset=research-bridges, /?preset=team-formation.

  • Turn this CSV of who emailed whom into a network, colour people by team, and give me a link.
  • Here are our vendors and the contracts between them. Size each vendor by how many contracts it holds and make link width the contract value.
  • Load this GraphML file, find its communities, and export a PNG for a slide.