Remote HTTP MCP

Remote HTTP is the MCP transport for hosted clients, CLI tools, and CI-like integrations. Instead of launching npm run mcp, the client connects to Ideagram's Streamable HTTP endpoint over a URL.

This is the alpha remote path. It uses personal access tokens today; OAuth + PKCE is the intended long-term remote authorization flow.

Connect Your Account

Create a personal access token in Settings > MCP Access and configure your client with the endpoint below plus Authorization: Bearer <your-token>. You do not need your user ID or any Supabase keys.

See Cursor, Claude Code, or ChatGPT compatibility. Clients must support the authentication method as well as Streamable HTTP.

When To Use It

Use remote HTTP when:

• the client is hosted, browser-based, or a CLI tool (Claude Code, Cursor, etc.);
• you want to create or edit diagrams, Pages, and Notes in your real Ideagram organization from outside the app;
• you need a stable URL-based integration for your alpha account.

Hosted Endpoint (ideagram.dev)

Ideagram's own alpha instance runs the remote MCP endpoint at:

https://ideagram.dev/mcp

Point any Streamable-HTTP-capable client at that URL with a personal access token (see Personal Access Tokens below) and it can list your organizations/workspaces/projects, create diagrams, Pages, and Notes, and read/write the project model — the same things you can do in the app, driven from a CLI, Cursor, Claude Code, or any other MCP client.

Health check:

GET https://ideagram.dev/healthz

Personal Access Tokens

Any signed-in user can create a token from Settings > MCP Access in the app:

1. Open Settings.
2. Select MCP Access.
3. Create a new token and choose its scope.
4. Copy the plaintext token shown once.
5. Revoke it from the same screen when it is no longer needed.

Configure the client with:

Authorization: Bearer idg_pat_...

Self-service PATs are hashed at rest. The plaintext token is shown once and is not stored.

PATs currently depend on the Supabase session from which they were created. If that session becomes invalid, sign in again and replace the PAT. Independent long-lived PAT sessions remain future work.

The HTTP transport is stateless: each POST uses fresh authentication and does not require a session ID. GET/SSE and DELETE return 405; clients use POST for tool calls.

Token Scopes

Scope	Behavior
read	Inspection tools; writes are blocked.
write	Permitted writes apply directly; can approve/reject pending changes.
propose	Decision/spec upserts are queued for review. Other permitted writes still apply directly; cannot approve its own proposals.

All scopes remain subject to the user's resource permissions. MCP access may be disabled for an organization by its feature configuration.

Env-Var Token Allowlist

This is an advanced server-operator fallback. Most users should create self-service tokens instead. Operators must provide a real identity and matching Supabase user access token:

$env:IDEAGRAM_MCP_HTTP_TOKENS='[
  {
    "token": "pat_example_do_not_commit",
    "userId": "<real-supabase-user-id>",
    "clientId": "cursor-staging",
    "supabaseAccessToken": "user-supabase-access-token",
    "readOnly": false,
    "expiresAt": "<future-ISO-8601-timestamp>"
  }
]'

The remote client sends the same header either way:

Authorization: Bearer pat_example_do_not_commit

CORS

CORS is opt-in. Set exactly one allowed origin:

$env:IDEAGRAM_MCP_HTTP_ALLOWED_ORIGIN="https://your-client.example"

Do not use wildcard origins for remote MCP.

Health Check

GET /healthz

returns:

{
  "ok": true,
  "service": "ideagram-mcp-http"
}