MCP server

Project88 exposes a hosted Model Context Protocol server so MCP-aware clients — Claude Code, Claude Desktop, Cursor, and others — can read from your org directly. No browser session, no copy-paste of data: the client calls tools against your org, and your permissions follow the token.

The server runs as the mcp Supabase Edge Function, speaks JSON-RPC 2.0 over Streamable HTTP (MCP 2025-06-18), and authenticates via per-user bearer tokens (p88_…).

What it exposes

Thirty read-only tools across the six native apps — Tables, Calendar, Dial, Inbox, Pages, and Templates — plus two system tools.

Notes:

• Row values on tables live in a data object keyed by column id. Call list_tables or get_table first to interpret them.
• Calendar collapses duplicate mirror copies of the same meeting and reports how many were merged.
• Dial calls the same dial_bucket_stats / dial_buckets_overview RPCs the app uses, so counts (including meetings) match what a rep sees in the shell.
• Inbox reads Gmail or Microsoft Graph through your own OAuth connection; prefer the batch get_email_threads over N calls to get_email_thread.
• Pages are serialized to markdown; if a block type isn't recognised, the response reports it in unrecognized_block_types rather than dropping content silently.
• Templates preserve merge tags ({{first_name}}) verbatim — they're content, not variables.

No write tools. No send, create, update, or delete surface exists. MCP clients call tools without confirming each one, so a hallucinated delete_event shouldn't be able to land in production data. A confirming write-tool surface is on the roadmap.

Connect Claude Code

1. Mint a token. In Project88: Settings → MCP access → Create a token. The raw value is shown exactly once — copy it now. Only a sha-256 hash is stored.

2. Export it in the shell you'll launch Claude Code from:

   export PROJECT88_MCP_TOKEN='p88_...'

3. Add a .mcp.json at the root of your project (Claude Code auto-loads it):

   {
     "mcpServers": {
       "project88": {
         "type": "http",
         "url": "https://<your-project-ref>.supabase.co/functions/v1/mcp",
         "headers": { "Authorization": "Bearer ${PROJECT88_MCP_TOKEN}" }
       }
     }
   }

4. Verify. Start a new session and ask "who am I in Project88?" — Claude should call whoami and name your user and org. Or check the connection listing:

   claude mcp list

Connect Claude Desktop, Cursor, or another MCP client

Any client that speaks the same JSON-RPC-over-HTTP transport works the same way. Point it at the endpoint from step 3 above and send the token as Authorization: Bearer p88_….

What a token can and cannot do

A token authenticates as one user in one organization. Every query runs through that user's own Row Level Security policies, so:

• It reads exactly what its owner can read in the app — no more.
• It cannot read another organization's data, even by accident — isolation is enforced by Postgres, not by application code remembering to filter.
• It stops working the moment its owner leaves the org, or the token is revoked.
• It is read-only.

The token grants your permissions to whoever holds it. Treat it like a password: keep it in an environment variable, never commit it.

Revoking

Settings → MCP access → Revoke token. Revocation is immediate — the server also drops its cached session for the token, so an in-flight client stops working at once. Tokens are revoked rather than deleted, so created_at and last_used_at survive for audit.

Conventions

Pagination. List tools take limit / offset and return pagination.has_more. An exact total is omitted unless you pass include_total: true — computing one is a full scan under the row's RLS predicate.

Errors. Tool failures come back as a normal result with isError: true and a plain-language message, so a model can recover. Database internals are never included; an unrecognised failure returns a generic message plus a short reference id that matches a server log line.

Ids. Tools expect table_id, event_id, bucket_id and friends as UUIDs. Get them from the corresponding list_* tool first — they aren't guessable.

How auth works (under the hood)

Each request carries Authorization: Bearer p88_…. The mcp function:

1. sha-256-hashes the token and looks it up in mcp_tokens;
2. exchanges it for a real user Supabase session for the token's owner (cached in-memory and in mcp_sessions with the live session held in Vault, so cold starts don't pay two round trips);
3. runs the tool's queries through that session — so RLS is the enforcement boundary, not .eq('org_id', …) filters written by hand in each tool.

Unknown, revoked, or non-p88_-prefixed bearer values are rejected with 401 Unauthorized.

The user-session model is what makes Inbox work at all: mailbox credentials in integrations are keyed by user_id, not org_id, so an org-only identity has nothing to resolve against.

Limits and caveats

• One user + one org per token. If you administer multiple orgs, or want to expose a different member's view, mint a separate token per scope and add each as its own MCP server entry.
• Read-only by design.
• Rate limiting. None yet at the MCP layer; upstream providers (Gmail, Graph) enforce their own. Per-token quotas will land before this surface is opened to end-customers.
• Inbox needs a connected mailbox. The user the token belongs to must have Gmail or Microsoft connected under Integrations; an unconnected user gets an explicit error, not empty results.

Troubleshooting

Where to next

• Tools — how Project88's own agents call tools
• Data tables — the shape behind query_table_rows
• Inbox — the mailbox surface behind the inbox tools
• Vault and secrets — how Project88 stores credentials in general