Connect an agent

A coding agent can read your saved connections through Alcuin, over the Model Context Protocol (MCP). It can list tables, describe them, run queries and explain them. It can never write: every statement runs in a read-only transaction that is rolled back.

Each agent client gets its own token, and the token says which connections, schemas and tables it may read. With no token, an agent can read nothing.

Agents are available on macOS and Linux.

Make a token

1. Open Settings (⌘, on macOS, Ctrl+, on Windows and Linux) and go to Agents.
2. Choose New token.
3. Enter a Name, such as claude-code: lowercase letters, digits, - and _. It names the client in history and in pg_stat_activity, as alcuin-mcp:claude-code.
4. Under Connections it may read, select each connection. Production connections stay grayed out unless you allow them (below).
5. Optionally, narrow what it may read:
   • Schemas, for example app, reporting. Empty means every schema.
   • Leave out tables, for example app.secrets, audit_log.
   • Leave out columns, for example users.email, *.password_hash.
   • Views it may read. Once a column is left out, a view could show it without naming it, so views are refused unless they are listed here.
6. Choose Make token. Alcuin asks you to confirm, listing exactly what the token can read, then shows the token once.
7. Copy the setup for your client from Setup for each client, while the token is on screen.

Alcuin keeps only a hash of the token, so it can’t show it again. If you lose it, make a new one.

Add Alcuin to your agent

Settings shows the setup for each client, with the token and the path to Alcuin filled in. Alcuin never writes another tool’s settings itself: you paste the setup where the client reads it.

Client	Where the setup goes
Claude Code	Run it in a terminal
Codex	~/.codex/config.toml
Cursor	.cursor/mcp.json, or ~/.cursor/mcp.json
VS Code	.vscode/mcp.json

For Claude Code, the setup has this shape:

claude mcp add alcuin-claude-code --env ALCUIN_MCP_TOKEN=<token> -- <path to Alcuin> --mcp claude-code

The client starts Alcuin with --mcp, and that connects to the Alcuin that’s running, over a socket only your user can open. If Alcuin isn’t running, it starts without a window, serves the agent, and quits a minute after the last agent session ends. While an agent is connected, the status bar says so: An agent (claude-code) is reading …, with the connection.

You’ll know it worked when your agent lists your connections: ask it which databases it can see. Its tools are list_connections, search_objects, describe_object, schema_summary, run_query, explain, activity and health.

What an agent may do

An agent can	Within these limits
Run one SELECT, EXPLAIN or SHOW at a time	Read-only and rolled back. Writes, SELECT … INTO, row locks and functions that act outside the transaction are refused
Read rows	500 rows and 64 KB per call, 5,000 rows per session. A value over 8,192 characters is cut
Keep sessions open	4 sessions per token. A connection closes after 5 minutes idle, or 30 minutes after it opened
Take time	On production, the token’s limit (15 seconds) or your Stop statements after rule, whichever is shorter. Elsewhere, your Stop statements after rule, or 60 seconds when it is Never. A lock is waited for 3 seconds
Explain a query	Explain with ANALYZE runs the statement, so it is off on production

When Alcuin refuses a request, the agent gets the reason as the tool’s result (ALC-4001), and usually rephrases.

No prompts, ever

Alcuin never asks you anything on an agent’s behalf. A statement your Safety rules would ask about is refused instead, with Agents are never asked to confirm: run it in Alcuin. You run it yourself, where you can see it.

You are asked twice, both times in Settings: when you make a token, and when you allow a suspended connection again.

Production

A token covers production connections only if you select Allow production connections when you make it. Rows the agent reads from production go to whatever model it uses, so a dedicated read-only role is the expected setup there. Write the statements for a dedicated role, in the token form, writes them for you to run: Alcuin never runs them.

Before you can save a production token, Check what its role can do looks at what the connection’s role could still do that a read-only transaction doesn’t stop. Select each line it finds, An agent with this token can still do this, and I accept it: …, to go on.

If a connection moves to production after the token was made, or points at another server, the token stops reading it. Its entry in Settings says Suspended: with the reason. Choose Allow again to let it read the connection as it is now. A token without production access can’t be allowed again on a production connection: make a new token.

See what agents ran

Every statement an agent runs, and every one Alcuin refuses, is in the History panel under Agents, kept apart from Yours. Each entry names the token. In the Activity view, an agent’s sessions show as alcuin-mcp:<name>.

Turn it off

There is no single switch. To stop one agent, choose Revoke token on its token in Settings, under Agents. Its open sessions are refused at once, with This token was revoked in Alcuin. Ask the user to make a new one. To turn agents off altogether, revoke every token. With none left, Settings says No tokens yet. An agent can read nothing until you make one.

Privacy says what leaves your computer when an agent reads.