MCP & Connectors — Developer Docs
Remote and local MCP servers, and how MCP tools map to REST operations.
How do I connect over MCP?
One MCP endpoint wraps the whole API: https://api.precisiondocs.ai/mcp, Streamable HTTP with OAuth 2.1 (dynamic client registration, PKCE S256, refresh-token rotation). The client opens your browser, you approve on the PrecisionDocs consent page, and the client holds a token scoped to your user and organization. No pd_live_ key is involved; the endpoint rejects one.
| Client | Setup |
|---|---|
| Claude Code | claude mcp add --scope user --transport http precisiondocs https://api.precisiondocs.ai/mcp, then /mcp -> precisiondocs -> Authenticate |
| OpenAI Codex | codex mcp add precisiondocs --url https://api.precisiondocs.ai/mcp, then codex mcp login precisiondocs |
| Gemini CLI | gemini mcp add --transport http precisiondocs https://api.precisiondocs.ai/mcp, then /mcp auth precisiondocs (the command writes {"url": "https://api.precisiondocs.ai/mcp", "type": "http"} under mcpServers.precisiondocs in settings.json) |
| Cursor | {"mcpServers":{"precisiondocs":{"url":"https://api.precisiondocs.ai/mcp"}}} in mcp.json, then sign in when Cursor asks |
| Claude app (claude.ai, Claude Desktop) | Settings -> Connectors -> Add custom connector -> paste the URL -> Connect |
| Any other MCP client | The URL alone. A client that only runs local stdio servers: npx -y mcp-remote https://api.precisiondocs.ai/mcp (the standard mcp-remote bridge, same browser sign-in) |
Discovery for a custom client: /.well-known/oauth-protected-resource/mcp names the authorization server, /.well-known/oauth-authorization-server lists authorization_endpoint, token_endpoint, registration_endpoint and revocation_endpoint. Disconnect a client any time from Account -> Integrations -> Connected apps; that revokes its token and refresh token immediately.
A long agent turn never times out. precisiondocs_ask_agent submits the turn asynchronously (wait: false): the API answers 202 with a job_id, the turn runs on a worker, and the tool polls GET /v1/projects/{id}/messages/{job_id} for up to 90 seconds before handing the model that handle to keep polling - always under the proxy read timeout, so no more opaque 524s. REST callers get the same contract by sending wait: false; wait: true still runs the turn synchronously in one request. If a transport error ever still says the turn may be running, do not re-ask (a second ask would charge a second turn): list the project messages and read the newest turn.
MCP tools and their REST equivalents:
| MCP tool | REST operation |
|---|---|
precisiondocs_plan_check | POST /v1/plan-check |
precisiondocs_resolve_parcels | POST /v1/parcels/resolve |
precisiondocs_preview_parcels | POST /v1/parcels/preview (returned to the client as an MCP image block) |
precisiondocs_create_project | POST /v1/projects |
precisiondocs_add_source | POST /v1/projects/{id}/sources, or POST /v1/projects/{id}/gis-sources when scope is given |
precisiondocs_list_projects | GET /v1/projects |
precisiondocs_get_project | GET /v1/projects/{id} |
precisiondocs_verify_zoning | PATCH /v1/projects/{id}/parcels/{i}/zoning |
precisiondocs_ask_agent | POST /v1/projects/{id}/messages |
precisiondocs_get_message | GET /v1/projects/{id}/messages/{turn_id} |
precisiondocs_list_messages | GET /v1/projects/{id}/messages |
precisiondocs_get_site_knowledge | GET /v1/projects/{id}/site-knowledge |
precisiondocs_export_gis | POST /v1/projects/{id}/gis-exports |
precisiondocs_create_map | POST /v1/projects/{id}/maps |
precisiondocs_get_site_plan | GET /v1/projects/{id}/site-plan |
precisiondocs_get_design_criteria | GET /v1/projects/{id}/design-criteria |
precisiondocs_get_yield_scenario | GET /v1/projects/{id}/yield-scenario |
precisiondocs_export_site_plan | POST /v1/projects/{id}/site-plan-exports |
precisiondocs_list_workflows | GET /v1/projects/{id}/interview/workflows |
precisiondocs_get_interview_step | GET /v1/projects/{id}/interview/step |
precisiondocs_answer_interview | POST /v1/projects/{id}/interview/answers |
precisiondocs_search_project | POST /v1/projects/{id}/search |
precisiondocs_generate_report | POST /v1/projects/{id}/reports |
precisiondocs_get_report | GET /v1/projects/{id}/reports/{job_id} |
precisiondocs_list_artifacts | GET /v1/projects/{id}/artifacts |
precisiondocs_get_artifact | GET /v1/projects/{id}/artifacts/{artifact_id} |
precisiondocs_get_wallet | GET /v1/wallet |
File uploads (POST /v1/uploads/initiate then POST /v1/uploads/{job_id}/finalize) are REST-only; the MCP tools cover URL sources.
For step-by-step setup with copyable configs, use the in-app Account -> Integrations wizard or the Help Center connector guides.