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://mcp.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://mcp.precisiondocs.ai/mcp, then /mcp -> precisiondocs -> Authenticate |
| OpenAI Codex | codex mcp add precisiondocs --url https://mcp.precisiondocs.ai/mcp, then codex mcp login precisiondocs |
| Gemini CLI | gemini mcp add --scope user --transport http precisiondocs https://mcp.precisiondocs.ai/mcp, then /mcp auth precisiondocs (the command writes {"url": "https://mcp.precisiondocs.ai/mcp", "type": "http"} under mcpServers.precisiondocs in settings.json) |
| Cursor | {"mcpServers":{"precisiondocs":{"url":"https://mcp.precisiondocs.ai/mcp"}}} in mcp.json, then sign in when Cursor asks |
| Claude app (claude.ai, Claude Desktop) | Customize -> Connectors -> Add custom connector -> paste the URL -> Add -> Connect (Team and Enterprise: an Owner adds it in Organization settings -> Connectors first) |
| ChatGPT | Plugins -> + -> Add custom MCP server -> paste the URL -> OAuth -> Create as a plugin (no such option: Developer mode under Settings -> Security and login) |
| Any other MCP client | The URL alone. A client that only runs local stdio servers: npx -y mcp-remote https://mcp.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 45 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.
Switch models by asking: Tell your connected assistant "use Claude Sonnet 5.5" or "switch to Auto". It reads precisiondocs_get_models and passes the approved model_id on subsequent precisiondocs_ask_agent calls. Auto is the default whenever no explicit choice is sent. A preference change itself does not run a paid turn; the assistant keeps it within your current conversation.
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_start_upload | POST /v1/uploads/initiate |
precisiondocs_finish_upload | POST /v1/uploads/{job_id}/finalize |
precisiondocs_dismiss_advisory | DELETE /v1/projects/{id}/advisories/{advisory_id} |
precisiondocs_list_projects | GET /v1/projects |
precisiondocs_get_project | GET /v1/projects/{id} |
precisiondocs_update_project_goal | PATCH /v1/projects/{id} |
precisiondocs_verify_zoning | PATCH /v1/projects/{id}/parcels/{i}/zoning |
precisiondocs_get_models | GET /v1/models |
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_get_study_area | GET /v1/projects/{id}/study-area |
precisiondocs_get_parcel_geometry | GET /v1/projects/{id}/parcels/geometry |
precisiondocs_set_study_area | POST /v1/projects/{id}/study-area |
precisiondocs_clear_study_area | DELETE /v1/projects/{id}/study-area |
precisiondocs_reapply_study_area | POST /v1/projects/{id}/study-area/reapply |
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_approve_program | POST /v1/projects/{id}/site-plan/program/approve |
precisiondocs_propose_concept | POST /v1/projects/{id}/site-plan/proposals |
precisiondocs_list_proposals | GET /v1/projects/{id}/site-plan/proposals |
precisiondocs_decide_proposal | POST /v1/projects/{id}/site-plan/proposals/{proposal_id}/approve or /reject |
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 |
precisiondocs_route | POST /v1/route: names the workflow a request asks for; the tool returns its tools in order, an argument sketch, the confirmations and the guide |
precisiondocs_get_docs | No REST call for a workflow guide (section set to a guide id such as maps-and-exports); otherwise the public OpenAPI spec (below), served as an index of every operation with the tool that calls it, its scope and its cost, or as one operation with its schemas resolved |
REST-only, each for a stated reason precisiondocs_get_docs repeats: PATCH /v1/projects/{id}/documents/{document_id} (no MCP read lists uploaded-document ids, and a display rename changes nothing an answer reads), GET /v1/projects/{id}/gis-exports/{artifact_id} (precisiondocs_get_artifact re-mints the same file), POST /v1/projects/{id}/summaries (the connected model summarizes itself, so a second model would spend credits for the same text) and GET /v1/projects/{id}/reports (precisiondocs_get_report and precisiondocs_list_artifacts cover it, and re-sending a report request attaches to the running job).
For step-by-step setup with copyable configs, use the in-app Account -> Integrations wizard or the Help Center connector guides.
How do I install the PrecisionDocs skill for Claude?
The PrecisionDocs Agent Skill teaches Claude the workflows behind the MCP tools: which tool answers what and in what order, what needs your confirmation, what spends credits, and every map and export PrecisionDocs makes, with how to put maps into a document. It is generated from the same source as the MCP server's own instructions, so the two never disagree, and it drives the connector above, which must be connected too.
| Client | Install |
|---|---|
| Claude Code (macOS, Linux, Git Bash) | curl -fsSL https://precisiondocs.ai/skills/precisiondocs.zip -o precisiondocs-skill.zip && unzip -o precisiondocs-skill.zip -d ~/.claude/skills && rm precisiondocs-skill.zip |
| Claude Code (Windows PowerShell) | Invoke-WebRequest https://precisiondocs.ai/skills/precisiondocs.zip -OutFile precisiondocs-skill.zip; Expand-Archive -Force precisiondocs-skill.zip "$HOME/.claude/skills"; Remove-Item precisiondocs-skill.zip |
| Claude app (claude.ai, Claude Desktop) | Download precisiondocs.zip, then open Settings, find Skills, choose Upload skill and pick the zip |
Claude loads the skill when a request fits it. Without the skill the same guides are one call away inside MCP: precisiondocs_get_docs with section set to a guide id (for example maps-and-exports), or with no section for the list of guides and the full API index.
Can I address PrecisionDocs by my agent name in Claude?
Yes. Name your agent under Account -> Profile -> Agent personality, the name the in-app chat already answers to. Every MCP session you connect opens its server instructions with that name (for example: The user calls PrecisionDocs "Atlas". A request to Atlas is a request to use these tools.) and names it on precisiondocs_ask_agent, so asking Claude "Atlas, what are the setbacks on my Maple Street project?" reaches PrecisionDocs instead of being answered from Claude's general knowledge.
The name is kept to plain name characters, up to 50. A name that already means Claude or any assistant (Claude, ChatGPT, Gemini, Copilot, Assistant, AI, Agent, Bot and similar) is not used for routing, because it would send your ordinary requests into paid agent turns; pick a distinct name such as Atlas. Claude reads the instructions when it connects, so after a rename start a new Claude session to pick it up.