Gate Wallet Auth Skill

Auth domain — Manage Google OAuth login, Token refresh, and logout. 5 MCP tools.

Trigger scenarios: User mentions "login", "logout", "authentication", "sign in", or when other Skills detect no mcp_token.

Step 0: MCP Server Connection Check (Mandatory)

Before executing any operation, you must first confirm that the Gate Wallet MCP Server is available. This step cannot be skipped.

Probe call:

CallMcpTool(server="gate-wallet", toolName="chain.config", arguments={chain: "eth"})

When Cursor is Not Configured

❌ Gate Wallet MCP Server Not Configured

The MCP Server named "gate-wallet" was not found in Cursor. Please configure it as follows:

Option 1: Configure via Cursor Settings (Recommended)
  1. Open Cursor → Settings → MCP
  2. Click "Add new MCP server"
  3. Fill in:
     - Name: gate-wallet
     - Type: HTTP
     - URL: https://your-mcp-server-domain/mcp
  4. Save and retry

Option 2: Edit config file manually
  Edit ~/.cursor/mcp.json and add:
  {
    "mcpServers": {
      "gate-wallet": {
        "url": "https://your-mcp-server-domain/mcp"
      }
    }
  }

If you don't have an MCP Server URL yet, please contact your administrator.

When Remote Service is Unreachable

⚠️  Gate Wallet MCP Server Connection Failed

MCP Server configuration was found, but the remote service cannot be reached. Please check:
1. Confirm the service URL is correct (is the configured URL accessible?)
2. Check network connection (does VPN / firewall affect access?)
3. Confirm the remote service is running

When API Key Authentication Fails

🔑 Gate Wallet MCP Server Authentication Failed

MCP Server is connected but API Key validation failed. The service uses AK/SK authentication (x-api-key header).
Please contact your administrator for a valid API Key and confirm the server configuration is correct.

Authentication Overview

This Skill is the auth entry point. Executing login itself does not require mcp_token. auth.refresh_token and auth.logout require an existing token.

After successful login, the obtained mcp_token and account_id will be passed to other Skills that require authentication (portfolio, transfer, swap, dapp).

MCP Tool Call Specification

1. auth.google_login_start — Start Google OAuth Login

Initiates Google Device Flow login and returns the verification URL the user needs to visit.

Call example:

CallMcpTool(
  server="gate-wallet",
  toolName="auth.google_login_start",
  arguments={}
)

Return example:

{
  "verification_url": "https://accounts.google.com/o/oauth2/device?user_code=ABCD-EFGH",
  "flow_id": "flow_abc123"
}

Agent behavior: Display verification_url to the user and guide them to complete Google authorization in the browser.

2. auth.google_login_poll — Poll Login Status

Uses flow_id to poll Google OAuth login result and determine whether the user has completed browser-side authorization.

Call example:

CallMcpTool(
  server="gate-wallet",
  toolName="auth.google_login_poll",
  arguments={ flow_id: "flow_abc123" }
)

status value meanings:

3. auth.login_google_wallet — Google Authorization Code Login

Uses Google OAuth authorization code to log in directly (for scenarios where a code is already available).

Call example:

CallMcpTool(
  server="gate-wallet",
  toolName="auth.login_google_wallet",
  arguments={ code: "4/0AX4XfW...", redirect_url: "http://localhost:8080/callback" }
)

4. auth.refresh_token — Refresh Token

When mcp_token expires, use refresh_token to obtain a new valid token.

Call example:

CallMcpTool(
  server="gate-wallet",
  toolName="auth.refresh_token",
  arguments={ refresh_token: "rt_xyz789..." }
)

Agent behavior: After successful refresh, silently update the internally held mcp_token; user is unaware.

5. auth.logout — Logout

Revokes the current session and invalidates mcp_token.

Call example:

CallMcpTool(
  server="gate-wallet",
  toolName="auth.logout",
  arguments={ mcp_token: "<current_mcp_token>" }
)

Skill Routing

After authentication completes, route to the corresponding Skill based on the user's original intent:

When other Skills detect missing or expired mcp_token, they also route to this Skill for authentication before returning to the original operation.

Operation Flows

Flow A: Google Device Flow Login (Primary)

Step 0: MCP Server pre-check
  ↓ Success
Step 1: Intent recognition
  Agent determines user needs to log in (direct login request, or redirected by another Skill)
  ↓
Step 2: Initiate login
  Call auth.google_login_start → Get verification_url + flow_id
  ↓
Step 3: Guide user authorization
  Display verification link to user, ask them to complete Google authorization in browser:

  ────────────────────────────
  Please open the following link in your browser to complete Google login:
  {verification_url}

  After completing, please tell me and I will confirm the login status.
  ────────────────────────────

  ↓
Step 4: Poll login result
  After user confirms authorization is complete, call auth.google_login_poll({ flow_id })
  - status == "pending" → Prompt user to confirm if complete, poll again later (max 10 retries, 3 sec interval)
  - status == "success" → Extract mcp_token, refresh_token, account_id, proceed to Step 5
  - status == "expired" → Prompt timeout, suggest restarting login
  - status == "error" → Display error message
  ↓
Step 5: Login success
  Store mcp_token, refresh_token, account_id internally (do not show token plaintext to user)
  Confirm login success to user:

  ────────────────────────────
  ✅ Login successful!
  Account: {account_id} (masked display)

  You can now:
  - View wallet balance and assets
  - Transfer and send tokens
  - Swap and exchange tokens
  - Interact with DApps
  - View market data

  What would you like to do?
  ────────────────────────────

  ↓
Step 6: Route to user's original intent
  Guide to the corresponding Skill based on user's initial request or follow-up instruction

Flow B: Token Refresh (Auto-triggered)

Trigger: Other Skill's MCP tool call returns token expired error
  ↓
Step 1: Auto refresh
  Call auth.refresh_token({ refresh_token })
  ↓
Step 2a: Refresh success
  Silently update mcp_token, retry original operation; user unaware
  ↓
Step 2b: Refresh failed
  refresh_token also expired → Guide user to re-login (Flow A)

  ────────────────────────────
  ⚠️ Session has expired. Please log in again.
  Initiating Google login for you...
  ────────────────────────────

Flow C: Logout

Step 0: MCP Server pre-check
  ↓ Success
Step 1: Intent recognition
  User requests logout / sign out
  ↓
Step 2: Execute logout
  Call auth.logout({ mcp_token })
  ↓
Step 3: Clear state
  Clear internally held mcp_token, refresh_token, account_id
  ↓
Step 4: Confirm logout

  ────────────────────────────
  ✅ Successfully logged out.
  To use wallet features again, please log in.
  ────────────────────────────

Flow D: Authorization Code Login (Alternative)

Step 0: MCP Server pre-check
  ↓ Success
Step 1: User provides Google authorization code
  ↓
Step 2: Execute login
  Call auth.login_google_wallet({ code, redirect_url })
  ↓
Step 3: Login success
  Extract mcp_token, refresh_token, account_id → Same as Flow A Step 5

Cross-Skill Workflow

Called by Other Skills (Auth Pre-requisite)

All Skills that require mcp_token should route to this Skill when they detect unauthenticated state:

Any Skill operation (requires mcp_token)
  → Detect no mcp_token or token expired
    → Auto try auth.refresh_token (if refresh_token exists)
      → Refresh success → Return to original Skill to continue
      → Refresh failed → gate-dex-mcpauth Flow A (login)
        → Login success → Return to original Skill to continue

Typical Post-Login Workflow

gate-dex-mcpauth (login)
  → gate-dex-mcpwallet (check balance/assets)   # Most common follow-up
  → gate-dex-mcptransfer (transfer)             # User explicitly wants transfer
  → gate-dex-mcpswap (Swap)                      # User explicitly wants swap
  → gate-dex-mcpdapp (DApp interaction)          # User explicitly wants DApp interaction

Edge Cases and Error Handling

Security Rules

1. mcp_token confidentiality: Never display mcp_token or refresh_token in plaintext to the user; use placeholder <mcp_token> in conversation only.
2. account_id masking: When displaying, show only partial characters (e.g. acc_12...89).
3. Token auto-refresh: When mcp_token expires, try silent refresh first; only require re-login if refresh fails.
4. No silent login retries: After login failure, clearly show error to user; do not retry repeatedly in background.
5. No operations when MCP Server not configured or unreachable: If Step 0 connection check fails, abort all subsequent steps.
6. Single session, single account: Maintain only one active mcp_token at a time; switching accounts requires logout first.
7. MCP Server error transparency: All MCP Server error messages are shown to the user as-is; do not hide or alter them.