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.
Add the hosted connector
Section titled “Add the hosted connector”The server URL is https://mcp.garphield.com/mcp. It needs no sign-in.
Claude
Section titled “Claude”- In claude.ai, open Customize > Connectors, select +, then Add custom connector.
- Name it Garphield, paste the server URL, and add it. It needs no OAuth client ID or secret.
- 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.
ChatGPT
Section titled “ChatGPT”- Open chatgpt.com/plugins, select +, then Add custom MCP server.
- Enter a name and the server URL, including
/mcp. Choose no authentication. - 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.
Coding tools
Section titled “Coding tools”Claude Code, Codex and Cursor can use the hosted connector too:
claude mcp add --transport http garphield https://mcp.garphield.com/mcp[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.
Stored graphs and expiry
Section titled “Stored graphs and expiry”- 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
.gphfile withgarphield_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_LIMITEDuntil 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.
Run garphield-mcp locally
Section titled “Run garphield-mcp locally”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:
claude mcp add garphield -- npx -y garphield-mcpAdd --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:
npx garphield-mcp create messages.csv --nodes people.csv -o team.gphnpx garphield-mcp inspect team.gphnpx garphield-mcp style team.gph --bind color=team --bind edgeWidth=messagesnpx garphield-mcp share team.gphPNG export needs playwright-core and a Chrome or Chromium browser; see the
package README for setup.
The tools
Section titled “The tools”| 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.
Resources for agents
Section titled “Resources for agents”| 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.
Example prompts
Section titled “Example prompts”- 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.