Remote MCP Connector (claude.ai)

The remote connector lets you add TokPortal directly inside claude.ai (web & mobile) or Claude Desktop as a "custom connector" — with a single URL and a one-click login. There is no JSON config file and no API key to copy: Claude sends you through a TokPortal sign-in and you approve access.

Prefer a local setup for Cursor, Claude Code, or your own agents? Use the npm package (tokportal-mcp) instead — it stays the right choice for stdio clients.

Connector URL

https://app.tokportal.com/api/ext/mcp

Add it in claude.ai

1. Open claude.ai → Settings → Connectors → Add custom connector.
2. Paste the connector URL above and confirm.
3. Claude redirects you to TokPortal. Sign in (or you're already logged in).
4. On the consent screen, choose Full access or Read-only, then click Authorize.
5. Done — TokPortal tools now appear in Claude. Try: "What's my TokPortal credit balance?"

The same steps work in the Claude mobile app and in Claude Desktop (Settings → Connectors → Add custom connector).

How authentication works

The remote connector uses standard OAuth 2.1 with PKCE — the same mechanism Claude uses for any remote MCP server:

• Claude discovers the authorization server from the connector URL automatically.
• You log in to TokPortal and approve in your browser. Your password and API keys are never entered into Claude.
• On approval, TokPortal mints a dedicated API key named Claude (MCP connector) and hands it to Claude as the access token.
• Every tool call Claude makes runs under your TokPortal account, through the same public API and the same rate limits as a normal API key.

Access levels

At sign-in you choose how much the connector can do:

Level	What Claude can do
Full	Read and write — create/configure/publish bundles, upload media, manage webhooks. Actions consume your credits.
Read-only	Read analytics, bundles, accounts and balances. No changes, no credit spend.

You can authorize twice (once Full, once Read-only) if you want both, and pick the connector per conversation.

Managing & revoking access

The connector is just a named API key. To see or revoke it:

1. Go to the Developer Portal → API Keys.
2. Find the key named Claude (MCP connector).
3. Revoke it — Claude immediately loses access and will prompt you to re-authorize next time.

Security notes

• Authorization codes are single-use, short-lived (10 minutes) and PKCE-bound (S256 only).
• The consent screen shows you exactly which destination the authorization is sent to (e.g. claude.ai). Only approve destinations you recognize.
• All traffic is HTTPS. The connector reuses the public API's authentication, rate-limiting and audit logging.
• Revoke anytime; nothing is stored on Claude's side beyond the issued token.

Tools & errors

The remote connector exposes the same 90 generated operations as local tokportal-mcp, from the same public OpenAPI schema. MCP tool discovery and the published OpenAPI document are the authoritative complete catalogues. This includes TokPortal Coverage through tokportal_get_account_managed_subscription, tokportal_reactivate_account_managed_subscription, and tokportal_cancel_account_managed_subscription. The stable technical field is named managed_subscription in API payloads. Reactivation uses the exact quote returned by the read tool, including valid zero-credit resumes, and refuses a changed quote without a debit.

The connector also exposes workspace-specific credit costs and the exact account reveal policy. Use the credit-cost tool as the pricing authority immediately before creation: the standard account setup price is 32 credits, Coverage is 25 credits every 30 days after the included first period, and Advanced Niche Warming has a 15-credit minimum. When contract_bundle_allowance is present, use its qualifier, live remaining quantity, prices and Coverage exemption. A slot is consumed atomically at successful bundle creation checkout, not at draft preparation or publication. On BUNDLE_PRICING_CHANGED, fetch costs again and retry with a new idempotency key. Ordinary account GET tools never expose TokMail addresses, passwords, social credentials, inbox data, or verification codes. Reveal policy is selected from the saved account creation cutoff: pre-cutoff accounts keep the prior 0-credit contract; later accounts require the returned policy_version and cost 150 credits unless Account Owning is approved. Account Owning Fee activation requires TokPortal admin approval after the 25-live-account and 25-percent-revealed threshold; the 150-credit reveal remains available while approval is pending. After approval, reveal activates or uses $10 per account every 30 days for an existing legacy agreement or $15 for a new agreement. The connector returns the same structured error diagnostics (request_id, retry_after_seconds, rate-limit headers). See the MCP Server page for commonly used tools and use tool discovery for the complete list.

The remote agent must first omit body and present the complete 428 policy preview to a human. It may send the accepted body only after explicit confirmation, using the exact returned policy_version and no idempotency_key. Secret-returning tools reject idempotency keys before execution. On CREDENTIAL_REVEAL_QUOTE_CHANGED, the agent must stop, fetch the new policy and price, and obtain fresh confirmation.

The same webhook contract reports eligible ban restoration through account.banned, subscription.ended and credits.restored. Restored account setup, warming and unused video-slot credits expire after 60 days; Coverage periods are never refunded.