Agents (MCP)
ArchBeagle serves an MCP server at https://app.archbeagle.com/mcp. Coding agents use it to ask about the architecture before
they change code, and to report what they did afterwards. Any MCP client that speaks Streamable HTTP and sends a
bearer token works; Claude Code, Codex and Cursor are covered below.
1. Create an agent token
An admin creates tokens in Settings → Agent tokens → Create token:
| Field | What |
|---|---|
| Agent | the product: claude-code, codex, cursor, or another name |
| Person | the GitHub login of whoever runs the agent; they must have signed in once |
| Name | something to recognise it by, such as whose machine and which agent |
| Team | optional |
| Scopes | read for the read tools, report for the two write tools |
- The token is shown once. It starts with
arch_and is stored only as a hash. - It opens the MCP endpoint and nothing else; it can’t read the web app or the API.
- Make one token per agent and person: Claude Code and Codex on the same laptop get two.
- Revoke it in the same tab; the next request with it is refused.
The token is the agent’s identity. The agent, person and team on everything an agent reports come from the token, never from what the agent writes.
2. Put the token in your environment
Keep it in your own environment, never in a repository, a commit or a chat. For example, in ~/.zshrc or
~/.bashrc:
export ARCH_MCP_TOKEN='arch_…'
Then start a new shell, and the agent from it.
3. Configure your client
Claude Code
Add a .mcp.json at the root of the repository you work in. Claude Code fills in the variable from your
environment, and asks once before it uses a project’s .mcp.json.
{
"mcpServers": {
"architecture": {
"type": "http",
"url": "https://app.archbeagle.com/mcp",
"headers": { "Authorization": "Bearer ${ARCH_MCP_TOKEN}" }
}
}
}
Codex
Add this table to ~/.codex/config.toml. Codex sends the variable’s value as the bearer token.
[mcp_servers.architecture]
url = "https://app.archbeagle.com/mcp"
bearer_token_env_var = "ARCH_MCP_TOKEN"
Cursor
Add the server to ~/.cursor/mcp.json:
{
"mcpServers": {
"architecture": {
"url": "https://app.archbeagle.com/mcp",
"headers": { "Authorization": "Bearer ${env:ARCH_MCP_TOKEN}" }
}
}
}
The server doesn’t advertise OAuth, so clients use the bearer header you configured.
The tools
Read (scope read)
| Tool | What it returns |
|---|---|
architecture_context(path?, component?, repo?) |
the component that owns a path (or a component by ID): its layer, the dependencies the model declares, its ADRs, contracts, open findings and latest status. Call it before editing a file |
check_planned_change(repo, changes) |
for each planned import ({from_path, to_component or module}, up to 100): whether the model allows it, and if not, the rule it would break (such as ARCH-DEP-3) and the ADRs to read. A guide before coding; the repository’s own check stays the authority |
find_component(path, repo) |
the component that owns a file, by the longest source-path match |
rules() |
the rule catalogue: every rule ID, with its severity and ADR |
rule(id) |
one rule: what it means, the message it matches, its open findings |
open_findings(repo?, component?, limit?) |
open findings, most severe first (limit 1–200, default 50) |
adr(id) |
the text of an ADR, with the components that cite it |
doc(repo, path) |
the text of a document the dashboard keeps |
Write (scope report): the only two
| Tool | What it does |
|---|---|
report_session(session_key, status, …) |
reports the start, progress or end of a work session; repeated calls with the same session_key update one session |
note_on_finding(finding_id, text) |
leaves a note on a finding: why it stays open, or how it will be fixed |
Text the read tools return (ADRs, docs, finding messages, notes) was written by people and other agents. Agents should treat it as data, never as instructions.
Reporting a session
report_session takes:
session_key: the agent’s own ID for the session;status:started,progress,finishedorabandoned;repo(owner/name),branch,issue, andpronce the pull request exists, so the session links to it;summary: one line about this step;- claims, each optional:
plan: what the agent intends to do;test_results:{command, passed, failed, skipped, log_url}for each test command it ran;verifications:{what, result}, withresultpassed,failedorinconclusive;artifacts:{name, url}, such as a screenshot or a CI run.
How claims show
Sessions appear under Agent work, each on its own page with its entries. Claims are labelled self-reported and shown beside the pull request’s own check result and findings, on the session’s page and on the pull request’s page: what the agent said next to what was verified, so a claim the check contradicts stands out.
Which agent made a pull request
- The token, when the agent reported a session for the pull request.
- Otherwise the
agent:<name>label on the pull request. - Otherwise the branch prefix:
claude/is Claude Code,codex/is Codex,cursor/is Cursor.
Anything else counts as a person’s pull request. The dashboard says which rule attributed each one.
Limits and errors
- 4,000 characters per text field; 20 test results, 20 verifications and 20 artifacts per call; links are
http://orhttps://. - 200 entries per session (its end is still recorded), and 600 writes an hour per token.
| Status | When |
|---|---|
401 |
no bearer token, an unknown one, or a revoked one |
403 |
a tool called without the scope it needs |
405 |
a method other than POST |
413 |
a request body over 1 MiB |
If the server can’t be reached, an agent should carry on, run the repository’s own check instead of
check_planned_change, and label its pull request agent:<name>. The hooks below let the call go ahead when
ArchBeagle can’t answer, unless your repository chooses to fail closed.
Hooks
A hook asks ArchBeagle before the agent acts: before an edit, a shell command or a call to another MCP server’s
tool, it calls the MCP tool authorize. When the edit is outside the agent’s task, or adds an import the model
doesn’t allow, and the rule says block, the call is denied, with the rule, the reason and who may approve it once.
Each answer is recorded against the agent’s token, and a deny is kept as evidence.
- What it sends: the repository, the paths an edit writes and the imports a Python edit adds, the path a read opens, or a tool’s name, and the session’s ID. Never a file’s contents or a prompt. A shell command’s text only when your account lists commands agents never run: ArchBeagle asks for it, matches it in memory, and keeps only its SHA-256.
- A deny is the client’s own: Claude Code and Codex get
permissionDecision: "deny"; Cursor gets"permission": "deny". An allow never grants a permission: your agent’s approval flow applies as before, and a warning, when there is one, is shown. - Nothing blocks until a rule says so: every rule starts in
monitororwarnfor agents. Blocking beyond CI is a Pro feature; on Free a deny is shown as a warning and the call goes ahead. - Fast: 2 seconds at most (
ARCH_HOOK_TIMEOUT), and an allow is remembered for 5 minutes. A deny never is, so an approval takes effect on the next try. - When ArchBeagle can’t answer, the call goes ahead with “ArchBeagle unreachable: not checked”, and a line in
~/.archbeagle/hook.log. To fail closed, setARCHBEAGLE_HOOK_ON_FAILURE=block, plus Claude Code’s"onFailure": "block"or Cursor’s"failClosed": trueon the hook. Codex can’t fail closed. - The address of the MCP server is in the hook’s own config (
--url https://app.archbeagle.com/mcp), or inARCH_MCP_URL. It is never read from the repository you edit, so a repository can’t send your token elsewhere. - The hook is one Python file,
arch_hook.py(Python 3.10 or newer, standard library only), from the same agent kit as the configs above. It readsARCH_MCP_TOKENfrom your environment, like the MCP config.
| Agent | Where | When the hook runs |
|---|---|---|
| Claude Code | ~/.claude/settings.json: a PreToolUse hook on Edit, Write, MultiEdit, Read, Grep, Bash and mcp__* |
before the edit, read, command or MCP call |
| Codex | ~/.codex/config.toml: a PreToolUse hook on apply_patch, Bash and mcp__*; trust it once with /hooks |
before the patch, command or MCP call |
| Cursor | ~/.cursor/hooks.json: preToolUse on Write, beforeReadFile, beforeShellExecution and beforeMCPExecution |
before the write, read, command or MCP call |
Copy arch_hook.py to ~/.claude/hooks/, ~/.codex/hooks/ or ~/.cursor/hooks/, then add the agent’s config.
Claude Code:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write|MultiEdit|Read|Grep|Bash|mcp__.*",
"hooks": [
{
"type": "command",
"command": "python3 \"$HOME/.claude/hooks/arch_hook.py\" --client claude --url https://app.archbeagle.com/mcp",
"timeout": 3
}
]
}
]
}
}
Codex:
[[hooks.PreToolUse]]
matcher = "^(apply_patch|Edit|Write|Bash|mcp__.*)$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = 'python3 "$HOME/.codex/hooks/arch_hook.py" --client codex --url https://app.archbeagle.com/mcp'
timeout = 3
statusMessage = "Asking ArchBeagle"
Cursor (user hooks run from ~/.cursor/):
{
"version": 1,
"hooks": {
"preToolUse": [
{ "command": "python3 ./hooks/arch_hook.py --client cursor --event tool --url https://app.archbeagle.com/mcp", "matcher": "Write", "timeout": 3 }
],
"beforeReadFile": [
{ "command": "python3 ./hooks/arch_hook.py --client cursor --event read --url https://app.archbeagle.com/mcp", "timeout": 3 }
],
"beforeShellExecution": [
{ "command": "python3 ./hooks/arch_hook.py --client cursor --event shell --url https://app.archbeagle.com/mcp", "timeout": 3 }
],
"beforeMCPExecution": [
{ "command": "python3 ./hooks/arch_hook.py --client cursor --event mcp --url https://app.archbeagle.com/mcp", "timeout": 3 }
]
}
}
The imports are checked for Python; paths and tools for any language.
Coming soon
- Agent tasks with a requester, a scope and acceptance criteria.