codesafe speaks the Model Context Protocol, so Claude Code, Claude Desktop, Cursor or anything else that speaks MCP can read your errors and act on them. One command, no plugin, no agent process to run.
Before you start
You need two things:
- codesafe's base URL, e.g.
https://yourcodesafe.cloud; - an MCP token — instance-level, issued by an administrator.
1. Get the token
An administrator generates it once:
php cli.php token generate mcp
It prints an .env snippet and changes nothing itself:
; POST /mcp — the agent endpoint
[MCP]
TOKEN = "…64 hex characters…"
Paste it into codesafe's .env and run php cli.php system cache clear, so the web side reads it. While no token is set, /mcp answers 404. MCP[TOKEN] is shared: every agent connected with it signs as mcp agent, and ACTIVITY cannot tell their clients apart.
A token per person. To see who did what, give each operator a token of their own under a label:
[MCP]
TOKENS = "anna:…64 hex characters…, bob:…64 hex characters…"
A label is 1–32 characters of a-z 0-9 . _ @ -; mint each token with php cli.php token random. Anna's writes are signed anna via mcp. Every token has the same scope (MCP[SCOPE], step 4).
In codesafe, the footer's ✦ AGENT button opens the CONNECT dialog, which hands you the finished command. The token is masked for everyone; an admin's REVEAL or COPY fills it in through an audited call, so who took the token is on record. Until MCP[TOKEN] is set the dialog stays dark.
2. Add the server
Claude Code
claude mcp add --transport http codesafe https://yourcodesafe.cloud/mcp \
--header "Authorization: Bearer YOUR_MCP_TOKEN"Claude Desktop / Cursor
{
"mcpServers": {
"codesafe": {
"type": "http",
"url": "https://yourcodesafe.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}Raw JSON-RPC
# everything the agent does is one POST; useful for testing the token
curl -s https://yourcodesafe.cloud/mcp \
-H "Authorization: Bearer YOUR_MCP_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"get_codesafe_info","arguments":{}}}'Two codesafe instances? Each needs its own server name — the field above the command in the CONNECT dialog sets it.
A proxy drops the Authorization header? Send the token as X-Mcp-Token: YOUR_MCP_TOKEN instead.
A wrong token answers 401 and is logged as an auth_failure on codesafe's own security channel, like a wrong password.
What the endpoint speaks. /mcp is stateless Streamable HTTP: one POST per JSON-RPC message, no session and no event stream (anything but POST answers 405). It speaks MCP revision 2026-07-28, which has no handshake, and 2025-11-25 and 2025-06-18, which open with initialize. A JSON-RPC batch — an array of messages — is refused.
3. Check it answered
Ask the agent to call get_codesafe_info. It is the first call any agent should make and it answers:
| field | what it tells you |
|---|---|
features | what is switched on here — AI, GitHub, pull requests, ticketing, inbox, automations |
scope | what this token may do |
projects, tools | how much it can see, how many tools it was offered |
release, retention_days | which codesafe it is talking to, and how far back |
4. Know what the token may do
The scope is instance-level: MCP[SCOPE] in .env, one of read, operate or admin. Left empty it is operate; any other value is read as read, so a typo never widens the token. Tools outside the scope are not offered to the agent at all — it cannot call what it cannot see.
| scope | what it adds |
|---|---|
read | the searches, gets and lists a viewer sees — nothing writes, and no AI model is asked (an analysis already kept is read). Not the project registrations and keys, the GitHub repositories, the improvements and the virtual-patch drafts, the box (get_system) or the storage sweep; get_fix_context holds back the repository code |
operate | (the default) plus the issue, rule and automation actions, monitors, the Shield and its virtual-patch drafts, the improvements, the AI calls and AI limits, the projects' settings and the rotation of their keys, the worker, the storage analysis and the reset of the AI counters |
admin | everything — the accounts, the purge, the audited reveal of a masked identity with the record of every reveal, a project's key in full (reveal_project_key) and the deletion of projects (delete_projects) |
The last two are an operator's in codesafe's own screens. Over MCP they are an admin's: a key an agent read has left codesafe, and a deleted project does not come back.
Some tools also wait for their feature: explain_issue, review_issue and ai_search need the AI; link_pull_request needs a forge (GitHub or GitLab); open_pull_request needs the AI and a forge codesafe may write to.
5. The three things agents are actually for
Triage. get_inbox is the landing question: what needs a person now, across issues, attack campaigns, CVE findings, late monitors and release cohorts — each row with the one action that is ready.
Fixing. The path is short and each step exists to save the next one work:
search_issues → get_issue → get_fix_context → (patch in your checkout)
→ set_issue_state resolved + set_issue_note
or link_pull_request, and codesafe verifies the fix itself
get_fix_context is the call worth knowing: one request returns the occurrence with its stacks and code slice, source slices from the mapped GitHub repository at the release ref, the suspect commits on a regression, the repo name so the agent can find the files in its own checkout, and the cached analysis. Under the read scope the repository slices and the commits are withheld.
Keeping the rules. list_rules, create_rule (with dry_run to preview a pattern against one project's stored events before writing it), update_rule, set_rule_mode, expire_rule, delete_rules; for automations list_automations, create_automation, update_automation, set_automation_enabled, delete_automations. Project names instead of ids, and every write leaves an audit line.
6. What it will not do
- It cannot exceed its scope. A
readtoken is a read-only codesafe. - Every write is audited, signed
mcp agentor the token's label (anna via mcp). Each one is a line on ACTIVITY that also names the client that sent it — Claude Code, Cursor, … as the client introduced itself (a labelled token's, or one the request names itself). An agent repeating one tool within a minute is one line with the count, so a sweep does not push the rest of ACTIVITY away; its AI readings (an analysis, a search, a review, rule proposals) leave none. - It does not destroy on the first call.
forget_ip,lift_shield_rule,set_shield_rule_mode,replace_shield_rule,restore_shield_rule,rotate_project_key,purge_alland everydelete_tool change nothing withoutconfirm: true; without it they answer what they would do. An agent asks you first, then confirms. - It reads outside text as data. Error messages, stacks, request fields, payload samples, a site's scan report, advisory text and the Shield rules learned from them arrive as
{"untrusted": …}in the answer, and the agent is told never to follow an instruction found in them — an attacker writes those strings. - It never merges. An agent can open a pull request and record what it found; a person merges it.
Next: Send your first error if codesafe has no data yet, or the API reference for the wire contract underneath.