Connect Codex or Claude Code to BLOM

How it works

Claude Code, Codex, or another agent reaches BLOM's MCP server at your organization's own address, with a key you make in BLOM:

https://blom.boundarylayerlabs.com/o/{organization id}/mcp

BLOM fills in your organization's ID wherever it shows the address. A key works only at its own organization's address.

The agent acts as the key's agent, never as you. Each change it makes records the agent, with you beside it as the person it answers to:

Claude · Ada Lovelace

BLOM coordinates and records your agent's work. It doesn't run your agent, and it runs no AI model of its own: you run Claude Code or Codex yourself, as usual.

Connect your agent

Connect Agent and Get started, on Atlas View, take you through the same steps. You copy the prompt first, and make the key when your terminal asks for it.

1. Copy the prompt

   In the rail, open Organization, then Connect Agent. Select Copy the prompt, and paste it into Claude Code, Codex, or another agent. It holds every instruction but the key. To read it first, open Show the prompt.

2. Run the command the agent gives you

   The agent works out which tool it is and which system you use, then asks you to run one command in your own terminal: PowerShell on Windows, Terminal on a Mac or Linux. The command asks for the key without showing it, and keeps it out of your shell's history. On a Mac, it asks for the key twice.

3. Make the key, and paste it there

   When the command asks, select Copy key in BLOM. Name the key, such as Claude, and select Make and copy key. BLOM makes the key and copies it. Paste it where your terminal asks, never into the agent's chat.

   BLOM shows the key's access, reach, and expiry in one line, such as "Read and write, across the organization, for 90 days". To choose otherwise, select Change. If one of your keys already has the name, BLOM offers Replace that key, which ends the old key at once.

4. Restart the agent

   The agent adds BLOM to its tool, then asks you to restart it: restart Claude Code, or quit Codex fully and open it again. In the new session, it reads BLOM's primer and tells you what it found.

Or start from API keys

You can also make the key first. In Organization, open API keys and select Create key. Name the key, change its access, where it reaches, or when it expires if you like, and select Create key. Agent keys explains each choice.

BLOM shows the Address and the Key, each with a copy button, then the same steps under Connect your agent: paste the prompt into your agent, run the command it gives you, and paste the key where the command asks. BLOM shows the key only this once.

What the agent sets up

The command keeps the key on your computer, under your tool's name rather than the key's:

The agent then connects to BLOM, reading the key from there, so the key never passes through its chat:

• Claude Code removes any earlier BLOM server, then adds BLOM at user scope with claude mcp add, so every project on the computer sees it.
• Codex puts BLOM's address in the [mcp_servers.blom] table of ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml), with bearer_token_env_var = "BLOM_KEY_CODEX". On a Mac or Linux, it also adds a line to your shell profile that sets that variable from the Keychain or the file.
• Another agent adds BLOM as a remote MCP server named blom, over HTTP, sending the key as Authorization: Bearer. If your tool can't, the agent stops and tells you, and you can connect by hand.

Check that it worked

• Your agent tells you which agent and organization it answered for, and which standards BLOM says are adopted, by name. If the agent or the organization is wrong, stop and fix the setup before it changes anything.
• Connect Agent and Get started show Waiting for Claude to connect… until the key's first call, then Connected: Claude reached BLOM. Select Check again to look at once.
• On API keys, the key's Last used shows when it last reached BLOM.
• In Claude Code, claude mcp list shows whether BLOM is connected. Don't run claude mcp get blom: it prints the key in full.

If it doesn't connect

When BLOM refuses a key, your agent tells you the recovery step the answer gives. A refused key is answered with an HTTP status, not a tool result:

Advanced setup

An Administrator can set an agent up step by step, for an agent that answers to someone other than you, names its provider, or, when your organization's teams are on, reaches a team. On API keys, select Advanced setup.

1. Register the agent

   Give its Name and What it runs on, choose its Accountable owner, the person who answers for it, and set its Delegated scope: Read at the organization, and Read and change on the products where it does task work. Select Register the agent, and BLOM opens the agent's page.

2. Grant its roles

   With Grant a role: Viewer at the organization, so its context exports carry the process and standards its tasks run under, and Editor on the products where it does task work.

3. Issue a credential

   With Issue a credential, give it a label if you like, choose when it expires, and select Issue the credential. BLOM shows the secret once, with your organization's address and the same prompt as a key's. An Administrator or the agent's accountable owner can issue one.

4. Connect it, and check its identity

   Paste the prompt into your agent, or connect it by hand. Make its first call a read, such as blom_read_primer. The answer's principal names the agent, as actorId, the Agent ID on its page, and the organization, as organizationId. If either is wrong, stop and fix the setup before any change.

The agent reaches only where its roles, its delegation, and its accountable owner's own access all reach. Its page shows the result under What it may reach now, and Change the delegation changes its scopes later.

Connect by hand

Each command asks for the key or credential at a prompt, so it stays out of the command and your shell's history. Replace {organization id} with your organization's ID, the one after /o/ in BLOM's addresses. BLOM fills it in for you under Do it by hand, beside a new key, and on Setup guide, on API keys.

Claude Code, at user scope, in bash:

read -rsp "BLOM credential: " BLOM_AGENT_TOKEN && echo && claude mcp add --transport http --scope user blom https://blom.boundarylayerlabs.com/o/{organization id}/mcp --header "Authorization: Bearer $BLOM_AGENT_TOKEN"

Or in PowerShell:

$token = Read-Host "BLOM credential"; claude mcp add --transport http --scope user blom https://blom.boundarylayerlabs.com/o/{organization id}/mcp --header "Authorization: Bearer $token"

For Codex, add BLOM to ~/.codex/config.toml (on Windows, %USERPROFILE%\.codex\config.toml). Codex reads the key from the variable it names:

[mcp_servers.blom]
    url = "https://blom.boundarylayerlabs.com/o/{organization id}/mcp"
    bearer_token_env_var = "BLOM_AGENT_TOKEN"

Then set BLOM_AGENT_TOKEN. In bash, it lasts while the terminal is open, so start Codex from it:

read -rsp "BLOM credential: " BLOM_AGENT_TOKEN && echo && export BLOM_AGENT_TOKEN

In PowerShell, it's kept for your Windows account. Quit Codex fully and open it again, from a new terminal if you start it from one:

[Environment]::SetEnvironmentVariable('BLOM_AGENT_TOKEN', (Read-Host "BLOM credential"), 'User')

Keep the key safe

• BLOM shows a key once. If you lose it, roll the key on API keys, then paste the new prompt into your agent.
• If a key leaks, roll it or revoke it at once. Either ends the old key immediately, and its work stays in the history.
• Claude Code keeps the key in its own configuration, in BLOM's server entry. That's why claude mcp get blom prints it.
• If you export a key from your shell profile, keep that file private: it then holds the key.

Related