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 the admin and client portals use. No separate database, no separate auth. Every agent call lands an audit-log row, so you can see exactly what the model did and when.

{
"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. Second call repeats the params plus the token. 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.

send_client_message is intentionally single-call — voice agents read the body aloud before sending, and the round-trip would slow down high-frequency client comms.

Auth model

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

The tool catalog

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

Not on the agent surface yet

Visible to humans in /admin but no MCP tool yet: calendar events, accepting the inbound approval queue, project-level discounts, recurring product costs, delivery requests, settings writes, and org-team CRUD. Need one end-to-end? 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 call lands an AgentAuditLog row — tool name, status, IP + user agent, duration, and the linked key. View recent calls under Settings → API Keys → Activity. The same data feeds daily_briefing's activity rollup (calls per day, error rate, top tools).