Connecting your coding agent to graphicle.dev

graphicle.dev is one MCP server: indexed, read-only copies of open-source repositories (code graph, symbols and sources) that your agent can search and cite. This guide gets your agent connected in a few minutes.

You need a token. It starts with gd_ and is shown to you once. Keep it out of files you commit: every example below reads it from an environment variable.

# in ~/.zshrc or ~/.bashrc
export GRAPHICLE_KEY=gd_your_token_here

The server is https://graphicle.dev/mcp (streamable HTTP). Every request carries Authorization: Bearer $GRAPHICLE_KEY.

roc (isolated agents in containers)

roc's graphicle server runs a local Graphicle by default. Point it at graphicle.dev with two variables:

export GRAPHICLE_URL=https://graphicle.dev/mcp
export GRAPHICLE_KEY=gd_your_token_here
roc -mcp add graphicle        # once; it's then on for every session
roc -doctor                   # shows graphicle as remote and ready

roc keeps the token on your machine: its gateway adds the header, so the token never enters the agent's container or its config files.

On an older roc without GRAPHICLE_URL support, add it as a remote server by hand:

roc -mcp add graphicle-dev=https://graphicle.dev/mcp
roc -mcp set graphicle-dev 'header.Authorization=Bearer ${GRAPHICLE_KEY}' requires=GRAPHICLE_KEY

If you use Toktail with roc, there's nothing more to do: Toktail drives the opencode session, and graphicle.dev reaches the agent through roc.

opencode

In opencode.json (your project's, or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "graphicle": {
      "type": "remote",
      "url": "https://graphicle.dev/mcp",
      "headers": { "Authorization": "Bearer {env:GRAPHICLE_KEY}" }
    }
  }
}

Claude Code

In .mcp.json at your project's root:

{
  "mcpServers": {
    "graphicle": {
      "type": "http",
      "url": "https://graphicle.dev/mcp",
      "headers": { "Authorization": "Bearer ${GRAPHICLE_KEY}" }
    }
  }
}

Codex

In ~/.codex/config.toml:

[mcp_servers.graphicle]
url = "https://graphicle.dev/mcp"
bearer_token_env_var = "GRAPHICLE_KEY"

Any other MCP client

Add a remote (streamable HTTP) server with the URL https://graphicle.dev/mcp and the header Authorization: Bearer <your token>.

Check that it works

curl -sS https://graphicle.dev/mcp \
  -H "Authorization: Bearer $GRAPHICLE_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A list of tools means you're in. 401 means the token is wrong, expired or revoked.

Private repositories

If your token includes private repositories, they're a second server: https://graphicle.dev/mcp/private, with the same header. Add it as another entry (for example graphicle-private) next to the first.

Tell your agent how to use it

Add this to your project's AGENTS.md (or CLAUDE.md):

## graphicle.dev
The graphicle MCP server has indexed copies of the libraries we use. Before
using an API you're not sure of, look it up there instead of guessing:
call list_projects once, then name the repository (`repo`) in recall_project,
query_graph, get_node and read_project_source. Cite repository, file and
lines. Respect each repository's license.

Limits

graphicle.dev serves a few agents at a time; the rest wait their turn. When it's busy you'll get 429 with Retry-After, and MCP clients retry on their own.
One request per token runs at a time, with one more waiting.
Every night at 3 AM New York time the shelf is re-indexed. When new repositories arrive, there's a short pause (503 with Retry-After).
A pass lasts 3 hours from its first request; the X-Graphicle-Expires header says when.

The current list of repositories is on the shelf, and agents can read llms.txt.