--- title: AI Connections, MCP & Developer API category: Integrations icon: 💻 sort_order: 22 excerpt: Connect compatible AI clients to an explicitly mapped internet-reachable vault through MCP. Phasoric Hosted, Dropbox, Google Drive, and GitHub mappings can be read when the account and mapping authorize them; externa… slug: developer-api-and-mcp canonical_url: https://phasoric.com/guides/developer-api-and-mcp markdown_url: https://phasoric.com/guides/developer-api-and-mcp.md --- # AI Connections, MCP & Developer API Connect compatible AI clients to an explicitly mapped internet-reachable vault through MCP. Phasoric Hosted, Dropbox, Google Drive, and GitHub mappings can be read when the account and mapping authorize them; external-provider note changes additionally require an explicit per-mapping MCP write grant. Premium and Professional include bounded MCP access for power users; Developer & Agent and Team add the separate Developer REST API and integration capabilities. A hosted service cannot read a local-only browser vault. ## Connect an application with OAuth (recommended) For ChatGPT web and other interactive remote MCP clients, add `https://phasoric.com/api/mcp`. The client discovers Phasoric's OAuth endpoints, sends you through normal Phasoric sign-in, and presents a Phasoric consent screen. You can approve read access, governed write requests, and optional continued access separately. Connected applications appear in **Settings → AI Connections & API → Connected applications** with their domain, permissions, connection date, and last use. Disconnecting an application invalidates its access and rotating refresh credentials without touching a separate manual token. OAuth access never uploads or exposes a local-only vault. It does not bypass a mapping's read/write setting, provider connection, device-held encryption, preview, revision, idempotency, plan, rate, monthly usage, or approval boundary. ## Manual Access Token Boundary 1. Open **Settings → AI Connections & API** and generate a bearer token. 2. Treat the token like a password. It is stored by Phasoric as a one-way hash and is bound to one account and its current plan entitlement. 3. Send `Authorization: Bearer bda_…` and the authorized mapping identifier expected by the surface: a hosted UUID for REST, or the opaque `mappingId` returned by MCP `list_vaults`. 4. Rotate or revoke the token from Settings if it may have been exposed. Every hosted vault query includes both the authenticated user ID and the explicit mapping ID. A token cannot address Phasoric’s public guide files, server filesystem, another user’s records, or an unspecified “current” vault. The manual token format is shared for simplicity, but authority is not: MCP and Developer REST independently resolve the account's current server-side plan on each request. A Premium or Professional token cannot use `/api/dev`. OAuth MCP tokens are a separate resource-bound credential and never authorize Developer REST. ## REST Developer API The REST gateway is mounted at `/api/dev` and provides: - `GET /notes?mappingId=...` for a bounded note inventory. - `GET /notes/:folder/:file?mappingId=...` for one hosted Markdown note and its revision hash. - `POST /notes` and `POST /transactions` for dry-run previews and explicit application. - `GET /events?mappingId=...` for the user-scoped provenance feed. Mutation requests default to dry-run. Applying a change requires `dryRun: false`, a valid idempotency key, and the current expected SHA-256 revision when changing or deleting an existing note. Multi-note writes commit in one database transaction. Deletes first create a recoverable hosted trash record. ## Model Context Protocol The hosted JSON-RPC endpoint exposes bounded tools for note search, note retrieval, WikiLink relations, frontmatter schema inspection, canvas-to-outline translation, guarded change preview/application, and provenance events. Vault tools require the opaque `mappingId` returned by `list_vaults`. Note changes default to preview and require explicit application, an idempotency key, and the current content hash for an existing note. Phasoric Hosted mappings are writable; Dropbox, Google Drive, and GitHub are writable only when the exact non-encrypted, non-pull mapping grants MCP changes and the provider connection has file-write capability. MCP uses its own monthly operation counter and per-minute request limit rather than consuming Developer REST API allowance. ## Automation Gateway `/api/dev/automation` is the reusable connection boundary for Zapier, n8n, Microsoft Graph ingestion, and custom webhook clients. It exposes: - `GET /catalog` and `GET /adapters/:bridge` for machine-readable capabilities. - `GET /openapi.json` for an OpenAPI 3.1 document that Zapier, n8n, and other orchestrators can consume. - `POST /events` for versioned `BasaltEvent` ingestion. - `POST /proposals` and `GET /proposals` for versioned, approval-required `ActionProposal` records. Both write endpoints require `Idempotency-Key`. Event payloads and proposal previews are size-bounded by their shared contracts. A bridge can propose an external action, but it cannot approve or execute it through this API; execution remains a separate Agent → policy → Forge → audit/undo path. Microsoft Calendar, Outlook mail, and OneDrive can arrive through the `microsoft-graph` ingestion adapter. That developer adapter remains intentionally ingestion-only and separate from Phasoric's native Microsoft account OAuth path; it never receives the native connection credential. ## Current Scope The supported gateway covers hosted-vault read/write, explicitly granted Dropbox, Google Drive, and GitHub note CRUD, remote-provider reads, provenance, bounded event ingestion, and Forge proposal creation. Native account connections cover Google Calendar, Gmail, Google Drive, Microsoft Calendar, Outlook mail, OneDrive, Dropbox, and GitHub within server-owned credential and capability policies. Linear, Jira, custom executable tools, and other long-tail systems use Zapier, n8n, OpenAPI, REST, MCP, or reviewed bridge-originated proposals rather than silent execution. Calendar and mail provider writes remain proposal-only until a capability-specific executor is available.