AI Connections, MCP & Developer API

For step-by-step ChatGPT, Claude, Codex, Cursor, and VS Code setup, use the MCP client setup guides in the Developer Center. See how agent memory works.

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.