💻

AI Connections, MCP & Developer API

Integrations
Listen to this page

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.