MCP integration

A Personal Server exposes an MCP server over streamable HTTP. A tool that serves scope contents resolves to the same read path as the HTTP API, behind the same grant check and the same access log. No client can reach more than the grant covers, and revoking the grant cuts off the client immediately. This is the integration path for an app whose consumer is an agent rather than a backend: the model discovers the user’s granted scopes, searches them, and pulls only the blocks it needs, instead of your code hard-coding a scope list.

Which surface you need

	Owner’s own client	Third-party app
Who connects	The user, with their own MCP client	Your app, on its own backend
Identity	A grantee keypair the Personal Server mints per connection and holds	Your registered builder address; you hold the key
How access is granted	OAuth-style consent inside Vana; the user picks scopes	An ordinary access request; the grant is issued to your app address
Authentication	Connection token from the OAuth flow	Short-lived bearer minted from a signed handshake
Reads are charged	No	Yes, when the grant is priced
Available for users on	Desktop app and web app	Desktop app only

The rest of this page covers the third-party path. On the owner’s path the user points their own client at their Personal Server’s /mcp URL and approves scopes in Vana; your app is not part of that flow.

The third-party flow

You sign once to mint a session token, then connect with an unmodified MCP client. The key never leaves your backend — the Personal Server only ever recovers your address, at the handshake.

Prerequisites

What	How
A registered builder identity	Your app address is registered at the DP RPC. See App identity
A grant issued to that address	An ordinary access request over the scopes your agent should reach. See Grants & permissions
The user’s Personal Server URL	Returned with the approved access request
A funded escrow	Only if the grant is priced. See Payments & fees

Step 1 — Mint a session

POST {personalServerUrl}/mcp/session
Authorization: Web3Signed <base64url(payload)>.<signature>

The signed payload is the standard Personal Server request envelope — aud, method, uri, bodyHash, iat, exp — and must carry a grantId claim. It is signed EIP-191 by your app key. A bearer token cannot open a session.

{
  "access_token": "vana_mcp_4b7e...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "oura.sleep chatgpt.conversations"
}

The handshake checks that your builder address is registered, the grant exists and is not revoked, the grant’s grantee is the handshake signer, and the grant’s grantor is this server’s owner. Scope coverage and revocation are checked again on every tool call, so revoking the grant stops the next call even inside an open session.

Session tokens do not survive a Personal Server restart, and a handshake proof is single-use. After a restart, sign a fresh proof and open a new session. Refresh the token before expires_in runs out instead of waiting for a 401.

Step 2 — Connect a stock MCP client

Point any streamable-HTTP MCP transport at {personalServerUrl}/mcp with Authorization: Bearer <access_token>, then call listTools() and callTool() as usual. The endpoint is stateless: each request carries the token, and no MCP session is kept between requests.

The tool catalog

Every tool is grant-scoped: a scope your grant does not cover returns scope_not_granted and the list of scopes that are covered.

Tool	What it does
`list_granted_scopes`	Granted scopes with readiness, size class, and a recommended access strategy. Call this first
`list_granted_sources`	The granted source ids, when you only need the sources
`list_scope_blocks`	A scope’s table of contents — block ids, paths, sizes — to feed into `read_scope`
`read_scope`	Read approved scope blocks; page with `nextCursor`, or pass exact `blockIds`
`search_personal_context`	Search across approved scopes; continue with `nextSearchCursor`
`get_scope_file`	Fetch an approved file or PDF scope, as metadata plus a resource link by default
`request_scope_access`	Report which requested scopes are missing from this grant, so the agent can ask the user to approve them in Vana

request_scope_access does not grant anything. It reports what is missing; the user approves additional scopes in Vana.

Paying for reads

When the grant is priced, a chargeable read answers with an x402 challenge rather than data:

{
  "payment_required": true,
  "status": 402,
  "challenge": { "x402Version": 1, "accepts": [ { "scheme": "vana-escrow-grant", "...": "..." } ] },
  "message": "This read requires payment. Sign the x402 challenge and call read_scope again with the `payment` argument."
}

Sign the challenge’s GenericPayment message with your app key — the same EIP-712 settlement the HTTP read path uses — and call the tool again with the base64 X-PAYMENT payload in its payment argument. read_scope and get_scope_file both take it. Design around three behaviors:

Search does not settle payments. search_personal_context is free discovery and preview. Chargeable scopes come back in paymentRequiredScopes; retrieve each through read_scope with a payment proof.
A 402 that will never clear is a different error. A genuine PAYMENT_REQUIRED carries a signable challenge. An empty escrow surfaces as payment_failed with no challenge — resolve the balance rather than signing in a loop.
Each cursor page and each retry is charged separately. A paginated read of one scope settles once per page. Budget for it, or read with explicit blockIds.

Reads under the owner’s own OAuth connection are never charged.

Limits

Read-only. MCP tools do not write. To store a result, use the Write API. To answer a question over data your app should not read, use derivative data.
Desktop app only for the third-party path. Users on the web app cannot open a third-party MCP session, so plan for your users to be on the desktop app.
The Personal Server must be reachable. A 503 can mean the server is offline or that the requested feature is not available on it; check the error code before retrying.
Sessions do not survive a Personal Server restart.

Auditability

The properties that make a grant safe apply unchanged to an agent:

Consent is on-chain — which app may reach which scopes, until when
Each scope-content read is logged in the Personal Server’s access log, attributed to your registered address, and every MCP tool call appears in an activity feed the owner can review
Each chargeable read settles a fee, leaving an on-chain record per use
Revocation is immediate — revoke the grant and the next tool call fails, without touching the session

Agents — why the protocol treats an agent as an ordinary grantee
Personal Servers — what serves the MCP endpoint
Grants & permissions — the grant an MCP session runs under
Derivative data — answering a question without reading the sources
Write API — storing a result back in the user’s Personal Server
Payments & fees — funding the escrow a paid read settles from

Overview

Protocol reference

Applications

Security

Network

Resources

Which surface you need

The third-party flow

Prerequisites

Step 1 — Mint a session

Step 2 — Connect a stock MCP client

The tool catalog

Paying for reads

Limits

Auditability

​Which surface you need

​The third-party flow

​Prerequisites

​Step 1 — Mint a session

​Step 2 — Connect a stock MCP client

​The tool catalog

​Paying for reads

​Limits

​Auditability

​Related

Which surface you need

The third-party flow

Prerequisites

Step 1 — Mint a session

Step 2 — Connect a stock MCP client

The tool catalog

Paying for reads

Limits

Auditability

Related