Source: https://developers.tokportal.com/mcp/remote/
Markdown: https://developers.tokportal.com/mcp/remote.md

# Remote MCP Connector (OAuth)

The **remote connector** lets you add TokPortal directly inside **claude.ai (web & mobile)**, **Claude Desktop**, **ChatGPT** or **Perplexity** 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**: the host sends you through a TokPortal sign-in and you approve access.

> Looking for Cursor, Claude Code, VS Code, Codex, Gemini CLI, Windsurf, n8n or a stdio setup? The [MCP Server page](https://developers.tokportal.com/mcp) has a copy-paste install snippet for every host.

## 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).

## Add it in ChatGPT or Perplexity

- **ChatGPT**: Settings → Connectors → Create (developer mode / custom MCP connectors must be available on your plan). Name `TokPortal`, URL `https://app.tokportal.com/api/ext/mcp`, authentication **OAuth**. Enable it per chat from the **+** menu.
- **Perplexity**: Settings → Connectors → Add connector → Custom, same URL, OAuth.

The consent screen and the access levels below are identical for every host.

## 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)`** (the same key name is used whichever host you connect from) and hands it to the host 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.

### Teams

If you were invited to a TokPortal [Team](https://app.tokportal.com/dashboard/settings?tab=team), the connector opens your **team's workspace**, not a personal one: the consent screen names the workspace owner, and every bundle, account, credit and subscription Claude sees is the team's. The key is minted in the owner's key list as **`Claude (MCP connector) · you@example.com`**, so the owner can tell whose assistant is behind it and revoke it. Two team permissions apply, set by the owner in Settings → Team: **API access** is required to connect at all, and **Spend credits** is required for a Full-access connector (a Read-only connector is always allowed).

## 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](https://app.tokportal.com/developer/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 91 generated operations as local `tokportal-mcp`, from the same public OpenAPI schema — see [What you can do](https://developers.tokportal.com/mcp#what-you-can-do) for the category breakdown. 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 is 5 credits per niche target (never per day) with 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](https://developers.tokportal.com/mcp#what-you-can-do) for the tool categories, the [428 confirmation policy](https://developers.tokportal.com/mcp#safety-the-428-confirmation-policy) and [troubleshooting](https://developers.tokportal.com/mcp#troubleshooting).

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.