# CooperBuild

> CooperBuild is the operating system for construction companies: estimating, proposals, procurement, submittals, pay apps, general ledger, payroll, field time, CRM, chat, and phone in one workspace. Named AI agents run on the customer's own Anthropic, OpenAI, Gemini, or xAI key.

Agents do not get an API key. They use OAuth 2.0 authorization code with PKCE (S256) and call the remote MCP server at https://api.cooperbuild.ai/mcp. The ChatGPT directory plugin uses https://api.cooperbuild.ai/mcp/directory. Scopes advertised by the authorization server: mcp:tools, mcp:read, mcp:write.

Unauthenticated POST https://api.cooperbuild.ai/mcp returns JSON-RPC -32000 with error.data.signup_url and error.data.authorize_url, and the same URLs on WWW-Authenticate. Human account signup is https://app.cooperbuild.ai/auth/signup.

## MCP session

After MCP initialize, every subsequent MCP request must reuse the mcp-session-id (or Mcp-Session-Id) response header. A bare tools/list without that header returns 400.

This applies to POST https://api.cooperbuild.ai/mcp and POST https://api.cooperbuild.ai/mcp/directory once initialize has returned that header. Send the same value on tools/list, tools/call, and every later request. The header name is mcp-session-id or Mcp-Session-Id.

Sample initialize. POST https://api.cooperbuild.ai/mcp with Authorization: Bearer <token>, Content-Type: application/json, and Accept: application/json, text/event-stream. protocolVersion is 2025-06-18. The OpenAPI document does not publish a different MCP protocol version. clientInfo.name and clientInfo.version are the client's own name and version. Reuse the Mcp-Session-Id response header on every later request.

POST https://api.cooperbuild.ai/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-agent",
      "version": "1.0.0"
    }
  }
}

## PKCE

code_verifier is a 43-128 character random URL-safe string. code_challenge is base64url(sha256(code_verifier)) with no padding. code_challenge_method is S256. Send code_challenge on POST https://api.cooperbuild.ai/api/agent/bootstrap and code_verifier on POST https://api.cooperbuild.ai/api/agent/bootstrap/verify and POST https://api.cooperbuild.ai/oauth/token.

OpenSSL:
code_verifier=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '='); code_challenge=$(printf '%s' "$code_verifier" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

Python:
import hashlib, base64, secrets
code_verifier = secrets.token_urlsafe(32)
code_challenge = base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode()).digest()).decode().rstrip("=")

Node:
import { createHash, randomBytes } from "node:crypto";
const code_verifier = randomBytes(32).toString("base64url");
const code_challenge = createHash("sha256").update(code_verifier).digest("base64url");

## Agent signup

A person creates the company at https://app.cooperbuild.ai/auth/signup, then connects the agent in the browser at https://app.cooperbuild.ai/oauth/authorize. Claude and ChatGPT use the Connect button, which opens that authorize page. Book a demo at https://cooperbuild.ai/demo. Sign in at https://app.cooperbuild.ai.

An agent with no person in the loop uses agent bootstrap. GET /health publishes the same URLs as agent_bootstrap.start, agent_bootstrap.verify, and agent_bootstrap.token. Inbox access is required. The 8-digit code expires in 15 minutes (900 seconds) by default.

1. POST https://api.cooperbuild.ai/oauth/register with Content-Type application/json. For agent bootstrap, POST /oauth/register with Content-Type application/json, redirect_uris, and token_endpoint_auth_method none. Recommend redirect_uris ["https://localhost/callback"]. A public client does not receive a client_secret. Use client_id plus PKCE. Omitting token_endpoint_auth_method registers client_secret_post and returns a client_secret, which is not the bootstrap client. The default scope is mcp:tools. mcp:tools alone is enough for MCP tools and satisfies agent HTTP read/write checks. scopes_supported also advertises mcp:read and mcp:write. Sending scope "mcp:tools mcp:read mcp:write" stores that trio on the client.

Register example:
{
  "redirect_uris": ["https://localhost/callback"],
  "token_endpoint_auth_method": "none"
}

2. POST https://api.cooperbuild.ai/api/agent/bootstrap with Content-Type application/json and email, company_name, client_id, code_challenge, and code_challenge_method S256
3. Read the 8-digit code from that email inbox before it expires (15 minutes / 900 seconds)
4. POST https://api.cooperbuild.ai/api/agent/bootstrap/verify with Content-Type application/json and email, code, client_id, and code_verifier. The response includes an authorization_code and redirect_uri
5. POST https://api.cooperbuild.ai/oauth/token with Content-Type application/x-www-form-urlencoded and grant_type authorization_code, code, client_id, code_verifier, and redirect_uri. redirect_uri must exactly match the redirect_uri returned by POST /api/agent/bootstrap/verify (e.g. https://localhost/callback). A public client has no client_secret. The response is a bearer token

Token example:
curl -X POST https://api.cooperbuild.ai/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d client_id=CLIENT_ID \
  -d code_verifier=CODE_VERIFIER \
  -d redirect_uri=https://localhost/callback

6. POST https://api.cooperbuild.ai/mcp with Authorization: Bearer and that token. After MCP initialize, every subsequent MCP request must reuse the mcp-session-id (or Mcp-Session-Id) response header. A bare tools/list without that header returns 400.

## Discovery

This guide is https://www.cooperbuild.ai/llms.txt. The API host does not publish it; requesting llms.txt there requires login.

- [Agent manifest](https://cooperbuild.ai/.well-known/agent.json): name, auth, endpoints, rate limits, pricing, safety
- [OpenAPI 3.1](https://cooperbuild.ai/openapi.json): the public HTTP surface and the MCP tools verified for estimates, vendor bids, proposal approval, and chat agents
- [Developer notes](https://cooperbuild.ai/developers#agent-bootstrap): cold agent signup, Mcp-Session-Id, and what is not published
- [Connect your agent](https://cooperbuild.ai/developers#agent-bootstrap): same path, linked from the homepage
- [JSON Schemas](https://cooperbuild.ai/schemas/mcp-jsonrpc.input.json): input schemas linked from the manifest
- Health: GET https://api.cooperbuild.ai/health (no auth). status ok, version 1.0.0, signup_url https://app.cooperbuild.ai/auth/signup, agent_bootstrap.start https://api.cooperbuild.ai/api/agent/bootstrap, agent_bootstrap.verify https://api.cooperbuild.ai/api/agent/bootstrap/verify, agent_bootstrap.token https://api.cooperbuild.ai/oauth/token
- Spend cap: GET https://api.cooperbuild.ai/api/agent/spend (bearer)
- Audit log: GET https://api.cooperbuild.ai/api/agent/audit (bearer)

## Rate limits

- 120 requests per minute, burst 40
- X-RateLimit-Limit: 160 (120 + 40)
- X-RateLimit-Remaining and X-RateLimit-Reset are sent on each response
- Retry-After is not sent

## Product

- [Home](https://cooperbuild.ai/)
- [Book a demo](https://cooperbuild.ai/demo)
- [Claude connector](https://cooperbuild.ai/claude): MCP URL https://api.cooperbuild.ai/mcp
- [ChatGPT plugin](https://cooperbuild.ai/chatgpt): MCP URL https://api.cooperbuild.ai/mcp/directory
- [Insights](https://cooperbuild.ai/insights)
- [Contact](https://cooperbuild.ai/contact)
- [Privacy](https://cooperbuild.ai/privacy)
- [Terms](https://cooperbuild.ai/terms)
- [Sign in](https://app.cooperbuild.ai)
- [Account signup](https://app.cooperbuild.ai/auth/signup): a CooperBuild account, not an API key

## Not published

- API key signup, key prefix, per-call price, and any API free-tier quota
- The Retry-After header
- Authenticated response bodies for GET https://api.cooperbuild.ai/api/agent/spend and GET https://api.cooperbuild.ai/api/agent/audit
- The GraphQL schema (POST https://api.cooperbuild.ai/graphql exists and requires a logged-in session)
- Output JSON Schemas for MCP tools