CooperBuild for agents

MCP session

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.versionare 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"
    }
  }
}

Agent signup

An agent with no person in the loop uses this path (agent_bootstrap_status: published). Human signup stays at https://app.cooperbuild.ai/auth/signup. Browser Connect stays at https://app.cooperbuild.ai/oauth/authorize. GET /health publishes the same three URLs.

Inbox access is required. The 8-digit code expires in 15 minutes (900 seconds) by default.

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 /api/agent/bootstrap and code_verifier on POST /api/agent/bootstrap/verify and POST /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");

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.
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 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.
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.

Register example. Content-Type: application/json. Recommend redirect_uris ["https://localhost/callback"].

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

Token example. Content-Type: application/x-www-form-urlencoded.

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

Documents

• /.well-known/agent.json — agent manifest
• https://www.cooperbuild.ai/llms.txt — short guide for language models. The API host does not publish this guide; requesting llms.txt there requires login.
• /openapi.json — OpenAPI 3.1
• /claude — connector setup for Claude (https://api.cooperbuild.ai/mcp)
• /chatgpt — plugin setup for ChatGPT (https://api.cooperbuild.ai/mcp/directory)

Authentication

Scheme is OAuth 2.0 authorization code with PKCE (S256). Send the access token in the Authorization header as a bearer token. There is no API-key prefix. Scopes advertised by the authorization server are mcp:tools, mcp:read, and mcp:write. The scopes document is https://api.cooperbuild.ai/.well-known/oauth-authorization-server.

• Authorization: https://app.cooperbuild.ai/oauth/authorize
• Token: https://api.cooperbuild.ai/oauth/token (Content-Type: application/x-www-form-urlencoded)
• Dynamic client registration: https://api.cooperbuild.ai/oauth/register (Content-Type: application/json, redirect_uris is required; recommend ["https://localhost/callback"]). Public-client and scope behavior is in Agent signup.
• In-app client credentials: https://app.cooperbuild.ai/mcp
• Account signup: https://app.cooperbuild.ai/auth/signup (auth.signup_url, signup_status: published). It creates a CooperBuild account. It does not issue an API key. There is still no API-key prefix (key_prefix: null, key_prefix_status: not_applicable).

Browser Connect

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.

Agent bootstrap

The cold path, including the inbox code and Mcp-Session-Id, is Agent signup.

Access tokens last one hour and refresh for up to 30 days. The connector acts as the signed-in user, inside that user's workspace.

POST /mcp without a token returns JSON-RPC -32000. error.data.signup_url and error.data.authorize_url include ?resource=https://api.cooperbuild.ai/mcp, and WWW-Authenticate repeats those URLs. GET /api/agent/spend and GET /api/agent/audit return the same challenge with HTTP 401. POST /mcp/directory uses resource https://api.cooperbuild.ai/mcp/directory.

Endpoints

Paths are on https://api.cooperbuild.ai. MCP tools are tools/call on POST /mcp. Output schemas are null because the tool descriptors publish input schemas only.cost and timeout_ms are null on every endpoint. idempotent: null means it depends on the method or tool and is not a single value.

• GET /healthPublic health check. No auth. Observed JSON has status ok, version, signup_url, agent_bootstrap (start, verify, token), and tools_after_auth (estimate_browse, estimate_manage, vq_browse, proposal_browse, search_projects, chat_agent_message). That list is not the full MCP catalog. signup_url stays the human browser signup. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Side effects: none. Idempotent: true. Auth: none.
• POST /mcpMCP JSON-RPC for the CooperBuild workspace. Bearer token required. After initialize, every subsequent request must reuse the mcp-session-id (or Mcp-Session-Id) response header. A bare tools/list without that header returns 400. Unauthenticated calls return JSON-RPC error -32000 with error.data.signup_url and error.data.authorize_url (resource https://api.cooperbuild.ai/mcp), plus the same URLs on WWW-Authenticate. Side effects: write. Idempotent: null. Auth: bearer.
• POST /mcp/directoryMCP JSON-RPC surface used by the ChatGPT directory plugin. Same bearer scheme. After initialize, every subsequent request must reuse the mcp-session-id (or Mcp-Session-Id) response header. A bare tools/list without that header returns 400. Resource metadata is at /.well-known/oauth-protected-resource/mcp/directory. Unauthenticated calls return JSON-RPC error -32000 with signup_url and authorize_url for resource https://api.cooperbuild.ai/mcp/directory. WWW-Authenticate uses resource_metadata for that protected resource. Side effects: write. Idempotent: null. Auth: bearer.
• POST /mcp · estimate_browseRead estimates, templates, deliverable classes, and task types. Side effects: read. Idempotent: true. Auth: bearer.
• POST /mcp · estimate_manageCreate, update, duplicate, import templates into, or soft-delete estimate worksheets. Side effects: write. Idempotent: false. Auth: bearer.
• POST /mcp · vq_browseFind trade scopes and read vendor quotes (bids) on a project or estimate. Side effects: read. Idempotent: true. Auth: bearer.
• POST /mcp · vq_quotePreview or record a vendor quote on a trade scope. confirm defaults to false and does not save. Side effects: write. Idempotent: false. Dry-run flag on the tool. Auth: bearer.
• POST /mcp · proposal_manageList proposal templates or create a client proposal from an estimate worksheet. Side effects: write. Idempotent: false. Auth: bearer.
• POST /mcp · proposal_approveApprove a proposal and copy its estimate onto the project. confirmApproval false previews; true performs the conversion. Side effects: irreversible. Idempotent: false. Dry-run flag on the tool. Auth: bearer.
• POST /mcp · talk_to_agentRoute a /slash, @mention, or #role message to one of the workspace's named chat agents and return that agent's instructions. Side effects: read. Idempotent: true. Auth: bearer.
• POST /mcp · chat_agent_messageHave a Cooper agent message a tenant user. confirm defaults to false and sends nothing. clientMessageId dedupes a real send. Side effects: external_message. Idempotent: false. Dry-run flag on the tool. Auth: bearer.
• GET /.well-known/oauth-protected-resourceOAuth protected-resource metadata for https://api.cooperbuild.ai/mcp. Side effects: none. Idempotent: true. Auth: none.
• GET /.well-known/oauth-authorization-serverOAuth authorization-server metadata, including scopes_supported, signup_url, agent_bootstrap_endpoint, and agent_bootstrap_verify_endpoint. Side effects: none. Idempotent: true. Auth: none.
• POST /oauth/tokenExchange an authorization code or refresh token. Content-Type application/x-www-form-urlencoded. Grants: authorization_code, refresh_token. The authorization_code grant requires grant_type, 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. Side effects: none. Idempotent: false. Auth: none.
• POST /oauth/registerDynamic client registration. Content-Type application/json. redirect_uris is required. Recommend redirect_uris ["https://localhost/callback"]. This does not mint an API key. For agent bootstrap, send token_endpoint_auth_method none and use the returned client_id with PKCE. A public client does not receive a client_secret. Omitting the auth method registers client_secret_post and returns a client_secret. Default scope is mcp:tools, which is enough for MCP tools and satisfies agent HTTP read/write checks. Sending scope "mcp:tools mcp:read mcp:write" stores that trio on the client. Side effects: write. Idempotent: false. Auth: none.
• POST /api/agent/bootstrapStart agent signup with no person in the loop. No bearer token. Content-Type application/json. JSON requires email, company_name, client_id, code_challenge, and code_challenge_method S256. Cooper emails an 8-digit code to that address. Inbox access is required. The code expires in 15 minutes (900 seconds) by default. GET returns 404. POST {} returns 400 invalid_request, email is required. An unknown client_id returns 400 invalid_client and points at POST /oauth/register. Side effects: external_message. Idempotent: false. Auth: none.
• POST /api/agent/bootstrap/verifyRedeem the emailed 8-digit code before it expires (15 minutes / 900 seconds by default). Inbox access is required. No bearer token. Content-Type application/json. JSON requires email, code, client_id, and code_verifier. The response includes an authorization_code and redirect_uri. POST /oauth/token uses Content-Type application/x-www-form-urlencoded. The authorization_code grant must send that redirect_uri unchanged (e.g. https://localhost/callback). GET returns 404. POST {} returns 400 invalid_request, email is required. Side effects: write. Idempotent: false. Auth: none.
• POST /graphqlGraphQL endpoint used by the web and mobile apps. Unauthenticated calls are rejected. No public schema is published. Side effects: write. Idempotent: null. Auth: session.
• GET /api/agent/spendSpend cap. Bearer token required. GET without a token returns 401 with signup_url and authorize_url. POST returns 404. The authenticated response body is not published. Side effects: read. Idempotent: true. Auth: bearer.
• GET /api/agent/auditAudit log. Bearer token required. GET without a token returns 401 with signup_url and authorize_url. POST returns 404. The authenticated response body is not published. Side effects: read. Idempotent: true. Auth: bearer.
• POST /api/landing-leadsPublic demo-request intake. No auth. name is required. Not part of the workspace MCP. Side effects: write. Idempotent: false. Auth: none.

POST /oauth/create-code is advertised as code_creation_endpoint. An empty body returns 400 because userTokenis required. The rest of that contract is not published, so it is in the OpenAPI file and not in the agent manifest's endpoint list.

Rate limits

The default allowance is 120 requests per minute, with a burst of 40. Responses on the API include X-RateLimit-Limit: 160 (120 + 40), X-RateLimit-Remaining, and X-RateLimit-Reset (unix time in seconds). Retry-After is not returned (rate_limits.status: published).

GET https://api.cooperbuild.ai/health needs no auth (health_status: published). The JSON includes status, version 1.0.0, signup_url, agent_bootstrap (start, verify, token), and tools_after_auth.

Safety

These tools require a confirmation flag before they change data. The first call, or confirm / confirmApproval left false, is the dry run. There is no site-wide dry-run header.

• proposal_approve — confirmApproval: true copies the estimate onto the project, approves the proposal, and creates the draft client invoice.
• vq_quote — confirm defaults to false and does not save the vendor quote.
• chat_agent_message — confirm defaults to false and sends nothing. clientMessageId dedupes a real send.

The audit log is GET https://api.cooperbuild.ai/api/agent/audit (audit_log_status: published). A bearer token is required. Without one the response is 401 and includes signup and authorize URLs. The authenticated response body is not in this manifest. Some tools accept an activityMessage that the workspace stores on the record.

Not published

These are null in the manifest on purpose. They are backend follow-ups, not values this site invented.

• self-serve API key signup and any key prefix
• per-call price and API free-tier quota
• Retry-After header
• authenticated response bodies for GET /api/agent/spend and GET /api/agent/audit
• GraphQL schema
• MCP tool output JSON Schemas
• request timeout_ms

Pricing that does exist: Cooper meters model usage, and the customer pays Anthropic, OpenAI, Google, or xAI on their own key. The spend cap is GET https://api.cooperbuild.ai/api/agent/spend (spend_cap_status: published). A bearer token is required. No per-call price or API free-tier quota is published, so free_tier and per_call stay null.

Questions: hello@cooperbuild.ai or the contact page. Machine-readable copies live at the manifest and the OpenAPI document.