supported

Model Context Protocol (MCP)

Connecting an existing agent? Start with Set up your AI agent, then follow the dedicated ChatGPT, Claude, Codex, Cursor, or VS Code / GitHub Copilot instructions. See the source-to-agent workflow.

Phasoric exposes a stateless MCP Streamable HTTP endpoint implemented with the official TypeScript SDK. It negotiates the current 2025-11-25 protocol revision and supported earlier revisions at:

POST /api/mcp

Machine-readable tool reference

The hosted endpoint is an authenticated AI-tool gateway over explicitly mapped internet-reachable content. It discovers Phasoric Hosted, Dropbox, Google Drive, and GitHub mappings owned by the authenticated account. Local-only browser state remains available only through the in-page WebMCP adapter described below.

External-provider mappings join two server-authoritative records on every call: the synchronized workspace mapping and the authenticated account's active provider connection with the required read capability. A provider connection by itself is not vault authority, and a mapping identifier by itself is not a credential. Device-encrypted BASALT-ENC-1 bodies remain inaccessible because their decryption key never leaves the device.

Published intelligence

Published Intelligence exposes individual hosted tools for search, state, changes, timeline, insights, and sources. Each accepts a product slug and explicit asOf cutoff, and resolves Intelligence Pack permissions and usage independently of raw vault ownership. get_published_intelligence_changes additionally requires from; search_published_intelligence requires question. No tool accepts an operation selector. Evidence includes source publication dates, locators and extraction versions.

Product-only programmatic callers can use POST /api/intelligence/mcp, which reuses hosted authentication and transport but permits only these six product tools. Existing private-vault MCP permissions are unchanged. WebMCP translates its first-party product operation to the corresponding hosted tool using the existing HttpOnly session bridge; it never queries a local corpus or bypasses the product MCP permission.

WebMCP / Site Tools

Phasoric exposes one versioned agent-tool contract through two transports:

Hosted MCP (/api/mcp) operates on explicitly mapped Phasoric Hosted or remote-provider vaults and accepts only the opaque mapping handles returned by list_vaults.
WebMCP registers first-party workspace tools with document.modelContext after the local workspace is ready. Its vault selector is vaultId; hosted MCP uses mappingId. The first-party adapter translates legacy product operations and the saved Quarry view name to the explicit hosted tools.

WebMCP vault IDs are opaque routing handles. local:<vault> executes against the active browser workspace; hosted:<mapping> forwards the call to hosted MCP. Agents should always call list_vaults and pass the returned vaultId rather than constructing one. If vaultId is omitted, WebMCP uses the currently selected local vault.

Forwarded hosted calls use the user's HttpOnly Phasoric session cookie. Page JavaScript never receives a bearer token. The server accepts session-authenticated MCP only when the request carries the WebMCP transport header, comes from a trusted Phasoric origin, and is same-origin or same-site. Hosted plan, rate, account, and monthly operation checks still apply.

The shared contract lives in shared/agent-tools.js, with explicit hosted operations in shared/hosted-mcp-operations.js. First-party mixed atomic note transactions use a session-only application endpoint; that dispatcher is unavailable through hosted MCP tools/call. OAuth and developer bearer credentials cannot access the session-only endpoint.

Standard Streamable HTTP lifecycle

Codex and other conforming clients begin with an initialize JSON-RPC request. Initialization, notifications/initialized, ping, tools/list, and tools/call use the standard Streamable HTTP path. Requests use these transport headers:

Authorization: Bearer bda_…
Content-Type: application/json
Accept: application/json, text/event-stream
MCP-Protocol-Version: 2025-11-25

The initialize request does not require MCP-Protocol-Version; subsequent standard requests send the revision negotiated by the initialize result. The endpoint returns JSON responses for client requests and does not expose a standalone GET event stream in stateless mode.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "phasoric-client", "version": "1.0.0" }
  }
}

The initialize result includes server-wide instructions telling agents to discover mappings first, respect bounded reads, and preview writes for human approval.

Legacy compatibility

Existing Phasoric integrations remain supported. A JSON GET request performs legacy discovery, and POST requests without the Streamable HTTP Accept header may use JSON-RPC server/discover, tools/list, or tools/call. The compatibility bridge also accepts Mcp-Method and Mcp-Name headers. An initialize body always takes precedence and enters the standard Streamable HTTP path.

Authentication

Phasoric supports two independent connection methods.

Account connection with OAuth (recommended)

Interactive remote clients should connect to the resource URL https://phasoric.com/api/mcp and perform OAuth discovery. Phasoric publishes Protected Resource Metadata and Authorization Server Metadata, accepts standards-based HTTPS Client ID Metadata Documents (CIMD), and retains Dynamic Client Registration (DCR) compatibility for public clients.

The authorization-code flow requires PKCE S256, exact redirect matching, OAuth state, and the exact resource indicator https://phasoric.com/api/mcp. The consent page explains the requested permissions before issuing a five-minute, single-use authorization code. Access tokens last one hour. When offline_access is granted, refresh tokens last up to 30 days, rotate after every successful use, and replay revokes the grant and token family.

Available scopes are:

Scope	Meaning
<code>mcp:read</code>	List authorized mappings and use search, note, graph, schema, canvas, provenance, and other read-only MCP tools.
<code>mcp:write</code>	Request note write/deletion previews or approved application, or `create_or_append_note`; mapping policy, revision, idempotency, and approval rules still apply.
<code>offline_access</code>	Receive a rotating refresh token so the client can remain connected.

OAuth tokens are audience-bound to the hosted MCP resource. They cannot authenticate /api/dev, capture, account, billing, or administration APIs. Each MCP request still resolves the account's current status, plan entitlement, rate limit, monthly allowance, mapping permissions, and write governance.

Review or revoke clients in Settings → AI Connections & API → Connected applications. Revocation immediately invalidates the grant and its access and refresh credentials; it does not change a manually managed developer token.

Manual bearer token (compatibility)

CLI, desktop, and development clients that cannot complete OAuth may generate a hosted access token from Settings → AI Connections & API. Phasoric stores only its hash and supports rotation or revocation:

Authorization: Bearer bda_…
Content-Type: application/json

Most vault tools also require a mappingId argument. Treat it as an opaque handle returned by list_vaults; do not construct it or assume it is always a raw UUID.

The same manually managed token may be used for both hosted MCP and the Developer REST API on Developer & Agent or Team plans. Each endpoint checks the account's current plan independently on every request. A Premium or Professional token therefore does not grant Developer REST API access. OAuth MCP tokens are never shared with the Developer REST API.

MCP operations use a dedicated monthly counter and request-per-minute boundary; they do not consume Developer REST API allowance. Authentication, inactive-account, entitlement, rate-limit, and monthly-limit rejections do not consume the monthly MCP allowance. Once an authenticated request reaches a recognized protocol or tool operation, it reserves one operation before execution, including a tool call that later fails argument validation. This prevents concurrent mutation requests from executing beyond the monthly allowance.

Initialization and discovery

Standard clients should use initialize. The legacy server/discover method remains available to older Phasoric clients:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "server/discover"
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "server": {
      "name": "phasoric-hosted-mcp",
      "version": "1.0.0",
      "protocolVersion": "2025-11-25"
    },
    "protocolVersions": ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"],
    "capabilities": {
      "tools": {
        "listChanged": false
      }
    }
  },
  "id": 1
}

List tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

The V1 implementation currently exposes these tools:

Tool	Purpose	`mappingId`
`search_published_intelligence`	Search accepted pack evidence for a question at a source-date cutoff	Product entitlement
`get_published_intelligence_state`	Read accepted pack assertions and evidence at a source-date cutoff	Product entitlement
`get_published_intelligence_changes`	Compare accepted pack evidence between two dates	Product entitlement
`get_published_intelligence_timeline`	Read source publication and reporting dates in a pack	Product entitlement
`list_published_intelligence_sources`	List admitted pack sources, citation URLs and versions	Product entitlement
`get_published_intelligence_insights`	Read existing derived pack insights available at the cutoff	Product entitlement
`get_intelligence_capabilities`	Reports hosted scope availability, bounded semantic reads and proposal-only capabilities	Required
`get_decisions`	Returns human-confirmed Strata decisions with status, temporal validity and source references	Required
`get_execution_trace`	Reconstructs a bounded work-session trace from currently authorized owner references; stale, missing or unpublished owners remain gaps	Required
`get_temporal_records`	Reads currently authorized temporal assertions in current, valid-at, known-at or history mode, with replica observation receipts	Required
`get_decision_evidence`	Returns authorized source blocks supporting a confirmed decision	Required
`find_related`	Returns typed explicit, semantic, evidence, decision, temporal and derived relationships	Required
`get_relationship_explanation`	Explains a typed relationship with source evidence and freshness	Required
`get_changes`	Returns deterministic hosted knowledge change events with before/after revisions	Required
`get_contradictions`	Returns recorded decision tensions without flattening history	Required
`get_open_questions`	Returns persisted, scope-authorized open questions and evidence references	Required
`get_commitments`	Returns persisted commitments and unresolved follow-up with provenance	Required
`query_saved_knowledge_view`	Query a versioned saved knowledge view (Quarry) inside the authorized Context Scope	Required
`get_watch_findings`	Returns authorized persisted Pulse Watch findings and review state	Required
`get_living_synthesis`	Returns authorized persisted living brief sections with evidence and review state	Required
`propose_knowledge_change`	Previews scope-authorized note changes through the guarded transaction service	Required
`propose_action`	Creates a Forge proposal containing a guarded note-change preview	Required
`list_vaults`	Discover authorized Phasoric Hosted and remote-provider mappings	Not required
`open_app_view`	Return a deep link to a supported Phasoric workspace view	Not required
`search_notes`	Search paths and bounded content in one available vault	Required
`get_note_content`	Read one available note and provider revision	Required
`create_or_append_note`	Preview/apply one authorized note write	Required
`query_graph_relations`	Query incoming/outgoing WikiLink relations	Required
`translate_canvas`	Convert bounded spatial nodes to a Markdown outline	Not required
`get_vault_schema`	Inspect bounded YAML frontmatter keys	Required
`preview_note_writes`	Preview a batch of note creations or replacements without applying	Required
`apply_note_writes`	Apply an explicitly approved batch of note creations or replacements	Required
`preview_note_deletions`	Preview a batch of note deletions without applying	Required
`apply_note_deletions`	Apply an explicitly approved batch of note deletions	Required
`get_knowledge_events`	Read provenance events for one mapping	Required

Call a tool

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_notes",
    "arguments": {
      "mappingId": "<value returned by list_vaults>",

Successful tool results use MCP-style content records. Tool failures may return JSON-RPC errors or an MCP isError result depending on whether the failure is protocol-level or tool-level.

Scoped trace and temporal reads

Both tools require an authorized contextScopeId and the transport-specific vault selector. get_execution_trace also requires sessionId. It reconstructs existing work-session references under current authorization; hosted reads use explicitly published owner records. Local agent runs are not published by the hosted adapter, so those references remain gaps. A complete returned graph does not establish universal capture or access to historical source bodies.

get_temporal_records accepts mode (current, valid-at, known-at, or history), an at timestamp for point-in-time reads, and optional entityType and entityId filters. Known-at evidence uses observation receipts owned by the receiving replica; author-supplied dates do not prove earlier availability. Missing legacy observations remain unavailable. Every mode still enforces current source authorization; it does not replay historical permissions.

Mutation safety

The note write and deletion tools and create_or_append_note use the Phasoric knowledge-transaction guardrail. Phasoric Hosted mappings retain their database transaction and recoverable-trash behavior. A Dropbox, Google Drive, or GitHub mapping becomes writable only when its owner enables Allow hosted MCP note changes for that exact mapping, the mapping is not pull-only, the active connection has provider file-write capability, and device-held vault encryption is disabled. Google Drive deletes move the note to Drive trash, and GitHub changes create commits on the mapped branch.

Use preview_note_writes or preview_note_deletions first. These tools always dry run and reject a dryRun override.
After human approval, call the matching apply_note_writes or apply_note_deletions tool with the exact approved notes. Each tool accepts a notes array with no action-type selector. Write entries require path and content; deletion application requires path and expectedHash.
Preview can omit expectedHash and returns the usable content hash in beforeRevision. Application to existing notes requires that current hash. Remote read revision is a provider revision; use contentHash from the read or beforeRevision from the preview for expectedHash.
create_or_append_note retains its default dry run and requires explicit dryRun: false for approved application.
Applied writes require an idempotency key.
Phasoric Hosted batch transactions are bounded and atomic.
Remote-provider previews may contain multiple actions, but an applied remote request is limited to one note per idempotency key because provider writes cannot be committed atomically with Phasoric's audit database.

An MCP client should preview the mutation, show the intended effect when appropriate, then explicitly apply the confirmed transaction.

Bounded inspection

MCP operations are intentionally bounded. Current implementation limits include:

search result limits;
bounded provider listings, folder traversal, total provider requests, operation wall time, body reads, and content-search downloads;
at most 500 canvas nodes for translate_canvas;
a bounded frontmatter scan for get_vault_schema (up to 2,000 Phasoric Hosted notes, or up to 20 live note reads inside an external-provider mapping);
bounded content used for graph/frontmatter analysis;
at most 100 actions in a note transaction.

Do not treat a truncated schema/graph response as proof that no additional information exists.

Governance boundaries

MCP does not create a second authority model. A tool call cannot legitimately:

read a local-only vault through the hosted gateway;
infer access to an arbitrary provider folder from a connected Dropbox, Google Drive, or GitHub account;
decrypt a remote note protected by a device-held vault key;
manufacture workspace/vault authority from a guessed identifier;
bypass current Context Scope/audience restrictions where a scoped Product Runtime workflow applies;
confirm a Strata decision merely because an agent generated it;
bypass Forge for consequential governed actions;
promote unreviewed model output to trusted shared memory.

Client configuration

For a manual desktop/CLI connection, generate a token in Settings → AI Connections & API, then expose it to the local Codex host as PHASORIC_MCP_TOKEN. Do not put the token itself in config.toml or a checked-in file.

Codex CLI and ChatGPT desktop

Add the Streamable HTTP server with the current Codex CLI:

codex mcp add phasoric --url https://phasoric.com/api/mcp --bearer-token-env-var PHASORIC_MCP_TOKEN
codex mcp get phasoric

The equivalent project-scoped .codex/config.toml entry is:

[mcp_servers.phasoric]
url = "https://phasoric.com/api/mcp"
bearer_token_env_var = "PHASORIC_MCP_TOKEN"
default_tools_approval_mode = "prompt"

In the ChatGPT desktop app, open Settings → MCP servers → Add server, choose Streamable HTTP, enter https://phasoric.com/api/mcp, save, and restart. The desktop app, Codex CLI, and IDE extension share MCP configuration on the same Codex host. Use /mcp to inspect the connected server.

The token environment variable must be available to the process launching Codex or the desktop app. Restart the application after adding or rotating it.

ChatGPT on the web

In a ChatGPT workspace where custom MCP connections are enabled, add https://phasoric.com/api/mcp as the remote MCP server. ChatGPT discovers Phasoric's OAuth metadata, opens the Phasoric sign-in and consent screen, and returns after authorization. Workspace administrator policy and the ChatGPT product's current connector availability still apply. No developer token needs to be pasted into ChatGPT.

After connecting, ask the client to call list_vaults. Explicitly mapped Phasoric Hosted, Dropbox, Google Drive, and GitHub vaults may appear. Local-only vaults are intentionally unavailable through this hosted endpoint.

list_vaults returns readOnly and writeAccess for each remote mapping. To authorize Dropbox, Google Drive, or GitHub CRUD, open Settings → Cloud Sync, select the exact provider mapping, and enable Allow hosted MCP note changes. Leave approval mode on prompt: the agent should preview first, then apply only the change you approve.