Code Caddie exposes a read-only MCP server at https://mcp.mycodecaddie.com. Any MCP-aware client (Claude Desktop, Claude Code, Cursor, custom agents) can connect, observe, and debug your projects — list files, grep code, read logs, invoke handlers to see their current behavior. The MCP cannot modify code, projects, keys, or certs. Code changes happen via the Code Caddie dashboard, the codecaddie-push CLI, or local Claude Code — each with a known developer in the loop.

1. Mint an agent API key

1. Open the project page for the project you want the agent to access and find the Agent Keys tab.
2. Enter a descriptive label (e.g. refactor-bot, nightly-deploy) so the key is identifiable in audit logs and the key list.
3. Tick only the scopes the agent actually needs. Start narrow — you can always mint another key. See scopes reference.
4. Click Mint key. A modal shows the raw key (cmsk_…) and the agent ID once. Copy the key immediately — only a SHA-256 hash is stored, so we genuinely cannot show it to you again.

2. Connect the agent

Three ways to wire an agent up, from most automatic to most manual.

A. MCP via browser login (OAuth) — recommended

For Claude Desktop, Claude Code, Cursor, or any MCP-aware client that supports OAuth. No API keys to paste; users log in through the browser and approve which projects the connector can access.

1. Open Claude Desktop → Settings → Connectors → Add custom connector.
2. Paste https://mcp.mycodecaddie.com and click Add. This is the same URL for every user — which projects the connector can touch is chosen at login, not baked into the URL.
3. A browser window opens at agents.mycodecaddie.com/oauth/authorize. Sign in with your Code Caddie email and verification code. The consent screen lists every project on your account; tick the ones you want this connector to access, and under each, the specific scopes (e.g. code:read, logs:read). Click Approve.
4. Claude Desktop finishes the exchange automatically. You should see code-caddie-platform in the connectors list with all platform tools ready.

The issued token is short-lived (1 hour) and rotates automatically via its refresh token (90 days). You can add more projects, change scopes, or remove projects from the connector anytime from the Code Caddie dashboard — changes apply to the live token immediately.

B. MCP via long-lived API key (config file)

Uses a cmsk_… agent key you minted in step 1. Good for scripts, CI runners, or MCP clients that don't support OAuth-based connectors yet.

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "code-caddie": {
      "url": "https://mcp.mycodecaddie.com",
      "headers": {
        "Authorization": "Bearer cmsk_YOUR_RAW_KEY_HERE"
      }
    }
  }
}

Fully quit and reopen Claude Desktop.

For Claude Code (CLI), add the MCP server with one command:

claude mcp add code-caddie https://mcp.mycodecaddie.com \
  --header "Authorization: Bearer cmsk_YOUR_RAW_KEY_HERE"

After connecting (both paths)

The client automatically pulls:

• An instructions block covering the platform's design (read-only nature, scope conventions, error envelopes, debug workflow). Injected into the model's context.
• A tool list with full input schemas (tree_list, file_glob, code_grep, file_read, files_read_batch, api_invoke, logs_get, etc.).

You only need to tell the agent one extra thing: which project ID to operate on (the 8-char hex id from the URL of this dashboard). The agent can also call projects_list to see what it's authorized for.

C. Raw REST (scripts, CI, non-AI integrations)

The same read-only surface that powers MCP is available as a REST API. Use it from scripts, workers, or any non-AI integration:

curl https://agents.mycodecaddie.com/projects/PROJECT_ID/read/api/hello.py \
  -H "Authorization: Bearer cmsk_..."

All endpoints echo X-Request-ID in the response for tracing. To make code changes, use the dashboard, codecaddie-push, or local Claude Code.

3. Scopes reference

The MCP is read-only, so the scope set is small. Mint keys with only what the agent needs.

Scope	What it grants
project:read	List/get projects, read project configuration (domains, cert status).
code:read	List/download files, grep, glob, read folder trees. Read-only view of a project's codebase.
executable:invoke	Run a project's /api or /executables handlers — useful for debugging current behavior. Note: this runs the handler, which may have side effects baked into the project author's code.
keys:read	List agent keys on projects this token holds access to. (Mint + revoke happen via the dashboard.)
logs:read	Read execution log files. Held separately from code:read so debugging access can be granted without granting log access (logs may contain user PII).

4. Repo-wide debug workflow

The MCP exposes Claude-Code-style filesystem read primitives, so MCP-only clients (notably Claude Desktop) can investigate a project without local sync:

Step	Tool	What it does
1	tree_list	Orient on the project structure.
2	file_glob	Narrow to files matching a pattern, e.g. **/*.py.
3	code_grep	Find files/lines matching a regex. Returns file:line refs.
4	file_read / files_read_batch	Fetch content for inspection. Batch up to 50 files in one call.
5	api_invoke / executable_run	Observe what a handler returns right now. Doesn't change the handler's code.
6	logs_list / logs_get	Read execution logs to diagnose handler behavior.

5. Revoke, audit, and delete

The Agent Keys tab on the project page lists every active key with its label, scopes, and creation date. Each row exposes:

• Revoke — flips the key's status to revoked. Subsequent calls return 401 unauthorized. The key metadata stays in the database for the audit trail. Always prefer revoke over delete.
• Audit — opens a view of the last events this key performed: action, timestamp, project, status code, request ID. Events are retained for 90 days, even after a key is revoked.

For OAuth-issued connectors, the dashboard shows them under the same Agent Keys tab with a "connector" label. Revoking an OAuth grant immediately invalidates both the short-lived access token and its refresh token; the MCP client will fail its next call and prompt for re-consent.