MCP server (AI agents)

The Contractor Codex ships its own Model Context Protocol server. Point Claude Desktop, Claude Code, or any MCP-compatible client at it, hand it an API key, and the model can run your portal — clock in and out, send invoices, draft quotes and contracts, mark payments paid, refund mistakes, post updates to your clients — without you opening the admin UI.

It sits on the same backend and database the admin and client portals use, but it has a separate authentication plane. MCP clients do not use your Clerk browser session: the ctsp_live_… Bearer key authenticates each request, and its scope and permissions limit what the caller can do. Every MCP tool call lands an audit-log row for operations review.

{
"mcpServers": {
  "contractor-codex": {
    "url": "https://contractorcodex.com/api/mcp",
    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
  }
}
}

claude mcp add contractor-codex --transport http \
--url https://contractorcodex.com/api/mcp \
--header "Authorization: Bearer YOUR_API_KEY"

How it works

Claude (or any MCP client)
  ↓  JSON-RPC over HTTPS, Bearer-token auth
https://contractorcodex.com/api/mcp
  ↓  validates token, checks your org's mcp_enabled flag
runAgentTool() dispatcher
  ↓  same handler as the /api/agent/<tool> HTTP route
your data

The MCP transport and the HTTP /api/agent/* routes call the same handler functions. Adding a tool exposes it on both surfaces at once — they never drift apart.

The mental model — three layers

Reading top to bottom, you get safer:

How the agent asks the right questions

Every write tool that takes a "which one?" parameter returns a structured needs_input response when called without it — instead of erroring. The response carries questions (what to ask), inventory (the real options — recent clients, draft invoices, available templates…), and next_step. The agent grounds in your actual data instead of inventing an ID.

AGENT → mark_paid()                              (no args)
      ← needs_input · inventory.open_invoices: [Henderson $2,400, Mosi LLC $800, …]
AGENT  "I see two open invoices for Henderson — $2,400 and $1,100. Which one?"
USER   "The 2400."
AGENT → mark_paid(snapshotId="…", method="check")
      ← confirmation_required · preview + confirmation_token
AGENT  "Mark the $2,400 Henderson invoice paid via check?"
USER   "Yes."
AGENT → mark_paid(snapshotId="…", method="check", confirmation_token="ct_…")
      ← marked_paid

The two-step confirmation rule

Every tool that sends an email, moves money, or destructively changes state goes through a mandatory two-step confirm, regardless of dollar amount:

1. First call returns confirmation_required + a confirmation_token + a preview the agent reads aloud.
2. The assistant reads that preview and waits for your explicit approval. Only then may it repeat the exact params plus the token so the tool executes.

Tokens expire after 60 seconds and are bound to (keyId, action, paramsHash) — they can't be replayed or reused for a different action. Receiving a token is not approval, and the assistant must never run both calls automatically.

send_client_message follows the same two-step confirm — it puts a real email in a client's inbox, so a human approval sits between the agent and the send.

Auth model

For a read-only key, untick every write group at creation — read tools require no write permission.

The tool catalog

89 tools, grouped by what they touch. Expand a group to see its tools.

Not on the agent surface yet

Kept out of the agent surface on purpose: removing or re-roling team members — inviting admins and client teammates is now invite_team_member / invite_client_teammate, but removals and role changes stay in the admin UI, since revoking the wrong person's access is the kind of mistake a confirmation prompt can't fully undo. Two more are intentionally not agent actions: approval decisions are client-side by design — the admin opens a request with request_approval, but accepting it is the client's consent to give, never the admin's (or an agent's) to make on their behalf; and the platform-fee / subscription / API-key / MCP-toggle settings are excluded from update_setting on purpose. Need a tool we don't have? Contact support — we ship new tools fast.

Troubleshooting

• Confirmation token expired — tokens TTL at 60s. Re-call the same tool without the token; the response carries a fresh preview.
• Insufficient permissions — the key lacks the right write group. Edit it under Settings → API Keys.
• Customer not found in this organization — an admin key passed a customerId from a different org. Keys never see across orgs.
• Stripe Connect is not configured — the org hasn't finished Connect onboarding. Call get_stripe_connect_status to see where they are; you can't send or collect invoices without it.

Best practices for client developers

1. Call get_context first. It returns the workflows map, inventory snapshot, system instructions, and endpoint catalog — the whole session leans on it.
2. Never pre-fill IDs from training data. When a tool returns needs_input with an inventory, use those IDs verbatim. Hallucinated IDs are the #1 failure mode.
3. Read previews back to the user word-for-word before the second (committing) call.
4. On second thoughts, start fresh. If the user changes their mind between calls, re-ask the params and issue a new token.
5. Use dry_run="true" on send_invoice / mark_paid to preview the dollar amount without locking a confirmation token.

Audit & observability

Every MCP tool call lands an AgentAuditLog row — tool name, status, IP + user agent, duration, and the linked key. These records are available for server-side operations and incident review. A per-key Activity screen is not yet exposed in Settings, and this data does not currently feed the daily briefing.