DOCUMENTATION

Connect your AI agent

codesafe speaks MCP: one command and Claude Code, Claude Desktop or Cursor can read your errors and act on them.

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:

fieldwhat it tells you
featureswhat is switched on here — AI, GitHub, pull requests, ticketing, inbox, automations
scopewhat this token may do
projects, toolshow much it can see, how many tools it was offered
release, retention_dayswhich 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.

scopewhat it adds
readthe 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
admineverything — 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 read token is a read-only codesafe.
  • Every write is audited, signed mcp agent or 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_all and every delete_ tool change nothing without confirm: 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.