Personal MCP

​

Choose the right credential

​

Create a token and connect

1. Sign in to Dashboard → Agent and open Personal MCP.
2. Name the credential, select only the scopes you need and choose an expiry of 1–365 days (default 30 days).
3. For models:invoke or utilities:invoke, bind one of your active API keys. Its model restrictions, budget and RPM remain effective. Reading account data does not require a positive balance.
4. Copy the mcp_user_ token when it is created into your client’s secret setting. Keep it out of source code, chat messages and logs. Revoke it in the same dashboard when access is no longer needed.

​

Discover tools before calling them

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_capabilities",
    "arguments": {}
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_balance",
    "arguments": {
      "input": {}
    }
  }
}

​

Permissions

​

Writes, results and safe retries

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "update_api_key",
    "arguments": {
      "input": {
        "key_id": "YOUR_KEY_ID",
        "rpmLimit": 60
      },
      "idempotencyKey": "set-key-rpm-20261106-01"
    }
  }
}

{
  "execution_id": "EXECUTION_ID",
  "replayed": false,
  "status": "completed",
  "data": {
    "balance": 100,
    "key": null
  }
}

​

Model and utility workflows

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "chat_completion",
    "arguments": {
      "input": {
        "body": {
          "model": "PUBLIC_MODEL_ID",
          "messages": [
            {
              "role": "user",
              "content": "Hello"
            }
          ],
          "stream": false
        }
      },
      "idempotencyKey": "chat-example-20261106-01"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "run_utility",
    "arguments": {
      "input": {
        "utility": "image-hash",
        "parameters": {},
        "files": {
          "image": [
            "YOUR_FILE_ID"
          ]
        }
      },
      "idempotencyKey": "image-hash-example-01"
    }
  }
}

​

Upload and retrieve files

1. Call begin_upload with filename, MIME type and exact byte size: at most 250 MiB.
2. Call upload_chunk with zero-based index and Base64 data. Each decoded chunk is at most 1 MiB; indices must be contiguous from zero.
3. Call finish_upload with file_id and optionally the lowercase SHA-256 checksum. Use the file only after status: ready.
4. Pass its ID to an accepting tool. get_artifact returns metadata, or Base64 bytes when offset is supplied. Follow next_offset until null. The download link requires signing in as the owner.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "begin_upload",
    "arguments": {
      "input": {
        "name": "example.png",
        "mime_type": "image/png",
        "size": 12345
      },
      "idempotencyKey": "upload-example-begin-01"
    }
  }
}

• upload_media: at most 20 files / 250 MiB total.
• upload_image: one file, at most 50 MiB.
• edit_image: at most 20 files across all fields, including at most one mask; 50 MiB per file / 100 MiB total. The per-field array limits in the input schema still apply.
• run_utility: the selected utility’s file-count, per-file and total limits from get_utility_schema apply, with a hard ceiling of 250 MiB total even when the catalog permits more.

​

Website confirmation and payments

• API key secret: start_reveal_key_action → user opens confirmation_url and approves → reveal_api_key with the returned action id as action_id. Approval is bound to that key and credential, expires 15 minutes after action creation and can be consumed once. create_api_key returns metadata only.
• Subscription cancellation: cancel_subscription starts confirmation. The user completes it on the website. Check get_account_action and subscription status before reporting completion.
• Password or account deletion: start_account_action with password_change or delete_account. The user handles email codes and passwords on the website, never through the assistant. Deletion revokes access and signs the user out; do not keep polling MCP after deletion.
• Payment: list_billing_products → create_checkout → user pays → get_payment_status. A checkout link does not prove payment.
• Real messages: resend_invoice and test_credit_alert send email or a webhook. Call them only when the user explicitly asks for that message.

​

Handle errors without duplicate work

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": "execution_pending",
      "message": "The original execution is pending; inspect its receipt before retrying",
      "status": 409,
      "execution_id": "EXECUTION_ID"
    }
  }
}

​

Useful read-only starting points

• Review spending: get_balance → summarize_usage → list_usage for individual requests.
• Explain a failed request: diagnose_request with its task_id; inspect the actual error and refund state before another model call.
• Prepare an integration: list_models → get_model_schema → get_api_guide; no model call is needed to read the guide.
• Review account security: list_api_keys → get_api_key → list_login_records.