Connect an agent

Updated 2 October 2026

Let an assistant search your reading library, summarize it, or make changes you request. Your client must support a remote MCP server over HTTP with a bearer key. Blackletter does not provide a browser OAuth sign-in flow.

Create a key

In Blackletter, open Settings → Connected agents → Connect an agent.
Give the connection a recognizable name. Keep read-only access for questions and summaries; turn on Allow changes only if you want this client to edit your library.
Choose an expiry of 30, 90 or 365 days, then create the key. Copy it before closing; Blackletter cannot show it again. Use a separate key for each client.

Keep the key in your client’s secret storage. Do not paste it into a conversation, source file or support request. The server URL is https://useblackletter.com/mcp.

Configure your client

Choose one setup below. For Codex and Claude Code, make the key available privately as the environment variable BLACKLETTER_AGENT_TOKEN before launching the client. Setting it in another terminal does not update an already running desktop app.

Codex

Add this to your Codex config.toml, usually ~/.codex/config.toml:

[mcp_servers.blackletter]
url = "https://useblackletter.com/mcp"
bearer_token_env_var = "BLACKLETTER_AGENT_TOKEN"

Launch Codex with the variable available, then check codex mcp list. See the official OpenAI MCP guide.

Claude Code

Add this to your project’s .mcp.json. Keep the variable reference as shown:

{
  "mcpServers": {
    "blackletter": {
      "type": "http",
      "url": "https://useblackletter.com/mcp",
      "headers": {
        "Authorization": "Bearer ${BLACKLETTER_AGENT_TOKEN}"
      }
    }
  }
}

Launch Claude Code with the variable available and check /mcp. See Claude Code’s MCP guide.

VS Code

For a local MCP session that supports interactive inputs, add this to .vscode/mcp.json. Start the server in VS Code’s MCP controls and enter the key in its password prompt:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "blackletter-key",
      "description": "Blackletter agent key",
      "password": true
    }
  ],
  "servers": {
    "blackletter": {
      "type": "http",
      "url": "https://useblackletter.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:blackletter-key}"
      }
    }
  }
}

Interactive inputs are not available in every Agent Host session. See the VS Code MCP reference for your session’s requirements.

Check the connection

Ask your assistant: “Use Blackletter’s get_me tool and tell me my handle.” Check that it is your account, then ask it to show your current reading shelf. A configured server alone does not prove that a reading request worked. The last authenticated request shown in Connected agents records access to the server, not completion of a particular task.

If access fails, check the URL, that the client received the key, and its expiry in Connected agents. A read-only connection has no change tools. Expired or revoked keys must be replaced. A client that requires browser OAuth sign-in cannot use this connection.

What access means

Read access includes your library and friend-visible book context you can already see in Blackletter. Change access lets an agent maintain books, progress, diary, rankings, reviews, passages, lists and goals. Keep your client’s confirmation controls for edits and deletions.

Agent changes create no feed posts or social notifications, but your reading keeps its normal visibility to friends. Agents cannot send friend requests, comments, recommendations or invitations, or change account and security settings.

Use Revoke key in Connected agents to stop future access immediately. Revoke a lost or shared key, then create a replacement. Signing out other app devices does not revoke agent keys.

For help, contact support with the client name and error, without the key.