Graphistry MCP

Graphistry exposes a Model Context Protocol (MCP) endpoint so an AI agent of your choosing — Claude, Cursor, an in-house agent, anything that speaks MCP — can operate a Graphistry visualization that a person already has open. The agent can read the graph's schema, run GFQL queries against it, and color subsets of it. Those changes appear live in the viewer's browser.

This is the same tool surface that powers Talk2Graph, made available to external clients. Talk2Graph is the built-in chat panel; the MCP endpoint is the same capability without the panel, driven by your own agent.

Before you start

• Talk2Graph enabled. The MCP endpoint is gated on it, so without it every tool call returns 403. It has to be enabled both for your account and for the Graphistry server you are calling — ask your Graphistry administrator for both, since having one without the other still fails. On Graphistry Hub the server side is already on, so contact Graphistry support.
• An open visualization session. Sessions exist because a person has a graph open in a browser. This server cannot create one — it can only attach to one that already exists.
• An MCP client that supports the Streamable HTTP transport and lets you set an Authorization header.

Endpoint

The server lives at /mcp on your Graphistry host, and speaks JSON-RPC 2.0 over Streamable HTTP.

Authentication

initialize and tools/list are open, so a client can discover the tool contract before anyone has signed in. tools/call requires a credential on the Authorization header.

Prefer a personal key. A JWT expires partway through a long agent conversation and the client starts getting 401 with no obvious cause; a personal key does not expire, so a long-running agent keeps working without reauthenticating. Create one at /users/personal/key/ on the Graphistry server you will be calling — keys are per server, so a key from one deployment will not authenticate against another. You need to be signed in to that server to create one. A key is a key_id and a secret; send the two joined by a colon, <key_id>:<key>. Sending the secret alone is rejected as a missing token.

A personal key is accepted under either the Bearer or PersonalKey scheme, because most MCP clients only give you a single "bearer token" field to fill in.

Client configuration

For MCP clients that read a JSON config file:

{
  "mcpServers": {
    "graphistry": {
      "type": "http",
      "url": "https://your-graphistry-host/mcp",
      "headers": {
        "Authorization": "Bearer ${GRAPHISTRY_PERSONAL_KEY}"
      }
    }
  }
}

For Claude Code, from the command line:

claude mcp add --transport http graphistry https://your-graphistry-host/mcp \
  --header "Authorization: Bearer $GRAPHISTRY_PERSONAL_KEY"

Connecting by hand

Useful for confirming credentials and network access before wiring up a client.

Set your credential first. A personal key is the key_id and the secret joined by a colon:

export GRAPHISTRY_HOST=your-graphistry-host
export GRAPHISTRY_PERSONAL_KEY='<key_id>:<key>'

1. Initialize, and capture the mcp-session-id header the response returns.

MCP_SESSION_ID=$(curl -si https://$GRAPHISTRY_HOST/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{
        "protocolVersion":"2024-11-05","capabilities":{},
        "clientInfo":{"name":"my-agent","version":"1.0"}}}' \
  | grep -i '^mcp-session-id:' | tr -d '\r' | awk '{print $2}')

echo "$MCP_SESSION_ID"

2. List the tools. Send the session id back on every subsequent request.

curl -s https://$GRAPHISTRY_HOST/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

3. Call a tool. This one needs the credential.

curl -s https://$GRAPHISTRY_HOST/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $GRAPHISTRY_PERSONAL_KEY" \
  -H "mcp-session-id: $MCP_SESSION_ID" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
        "name":"list_sessions","arguments":{}}}'

Two kinds of session

The word "session" means two different things here, and mixing them up is the most common source of confusion.

Get a session_id one of two ways: ask the person with the graph open for the session= value in their visualization URL, or call list_sessions, which returns sessions opened by your own account. Prefer the URL when you have it — list_sessions is occasionally incomplete. Do not substitute or guess one; a session id that is not live returns 410.

Who can do what

Access is decided per call, against the credential you sent.

• The session owner — the person with the graph open — may call every tool.
• Anyone else may call read tools only (list_sessions, get_session_info, query_graph, list_collections), and only if they are entitled to view that dataset. Tools that mutate the graph are refused with 403.

A 503 means the authorization check could not be completed. The call was refused, not permitted — retry it.

What the agent can do

Nine tools, covering inspection, querying, and coloring. See the Reference for arguments and return shapes.

The graph query language is GFQL, passed as a JSON string. Agents that have not seen GFQL before write queries that return zero rows without erroring, so validate an expression with query_graph before using it to create a collection. Graphistry publishes an agent skill covering the query patterns and the pitfalls at graphistry/graphistry-skills; install the graphistry-mcp skill into your client and results improve markedly. The GFQL documentation covers the language itself.

Troubleshooting