# 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.

```sh
# 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:

```sh
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:

```sh
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`):

```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:

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

## Codex

In `~/.codex/config.toml`:

```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

```sh
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`):

```markdown
## 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](https://graphicle.dev/#shelf), and agents can read [llms.txt](https://graphicle.dev/llms.txt).