coros-mcp

intent

use this skill when you need to establish or refresh a coros mcp login session through the global gateway at mcp.coros.com. the gateway automatically resolves your request to the appropriate regional cluster (cn, eu, or us) and pins all subsequent token refresh, mcp calls, and local cache files to that concrete issuer. pick this over direct cluster urls when you want automatic regional routing and when you need the session to survive browser-on-different-machine scenarios or cli process interruptions.

inputs

required binaries:

• python3 (3.8+)
• openclaw (installed locally)

required external connection:

• coros mcp gateway at https://mcp.coros.com (no api key needed for discovery; oauth2 device flow or legacy username/password)

optional environment overrides:

• COROS_ISSUER: force a specific regional issuer (https://mcpcn.coros.com, https://mcpeu.coros.com, or https://mcpus.coros.com). if unset, gateway discovery selects the region.
• COROS_MCP_SKILL_HOME: override the default local cache directory (~/.coros-mcp-skill-gateway/). useful for testing or multi-user setups.

skill directory structure:

• this skill includes scripts/coros_mcp_login.py, which orchestrates all login, token, and mcp interactions.

procedure

1. cd to this skill's root directory (where scripts/coros_mcp_login.py exists).

2. choose your flow based on setup context:

   • if user and browser are on the same machine and cli will stay alive, use one-shot flow (steps 3a).
   • if browser may be on a different machine or cli might disconnect, use two-step resilient flow (steps 3b).

3a. one-shot flow (single machine):

• run: python3 scripts/coros_mcp_login.py apply-openclaw --server-name coros
• the helper defaults to https://mcp.coros.com, discovers the gateway-selected regional issuer, and completes login (browser or legacy password) in one call.
• skip to step 10.

3b. two-step resilient flow (cross-machine or interruptible):

• step 1: run python3 scripts/coros_mcp_login.py login-start on the original machine. this prints a browser login link and saves pending login state locally.
• step 2: user opens the browser link on any device and completes coros login.
• step 3: run python3 scripts/coros_mcp_login.py login-finish on the original machine to finalize token save.
• step 4: run python3 scripts/coros_mcp_login.py apply-openclaw --server-name coros to register the mcp entry in openclaw.

4. inspect available tools (after login succeeds, anytime before calling tools):

   • run: python3 scripts/coros_mcp_login.py list-tools
   • this reuses a short-lived local tool catalog cache; results are fast on repeated calls.
   • output: json list of tool names and descriptions.

5. refresh tool catalog only when needed (e.g., after server update):

   • run: python3 scripts/coros_mcp_login.py list-tools --refresh
   • forces a live re-fetch from the server's /mcp endpoint, bypassing local cache.

6. before calling an unfamiliar tool, inspect its schema:

   • run: python3 scripts/coros_mcp_login.py describe-tool --tool <toolname>
   • example: python3 scripts/coros_mcp_login.py describe-tool --tool queryUserInfo
   • output: full json schema (parameters, required fields, types).

7. call a tool with explicit arguments:

   • run: python3 scripts/coros_mcp_login.py call-tool --tool <toolname> --arguments-json '<json_object>'
   • example: python3 scripts/coros_mcp_login.py call-tool --tool queryUserInfo --arguments-json '{}'
   • the helper automatically refreshes the token if near expiry before making the mcp request.
   • output: json response from the mcp server.

8. verify openclaw registration (after apply-openclaw succeeds):

   • run: openclaw mcp show coros
   • output: mcp entry config (issuer, server name, endpoint).

9. report results to user (see outcome signal section for exact format).

decision points

if browser-based login succeeds on first attempt:

• proceed to step 8. token is cached locally under ~/.coros-mcp-skill-gateway//.

if browser login link is printed but user cannot open browser on this machine:

• use two-step flow instead. run login-start, have user open the link on another device, then run login-finish on the original machine.

if legacy password flow is explicitly requested by user:

• pass --legacy --username <username> to apply-openclaw or login-start. password will be prompted interactively (never passed as argument).
• example: python3 scripts/coros_mcp_login.py apply-openclaw --server-name coros --legacy --username myuser

if token is near expiry (< 5 min remaining):

• list-tools, describe-tool, and call-tool automatically refresh the token before executing. no manual refresh needed.

if local token cache exists and is still valid:

• apply-openclaw and tool operations reuse the cached token. no new browser login is triggered.

if local token cache is missing or expired:

• apply-openclaw triggers the browser login flow (or prompts for password if --legacy is set).

if list-tools or describe-tool results are stale and you need the latest live catalog:

• pass --refresh to force immediate re-fetch from /mcp endpoint, skipping the short-lived local cache.

if you must use a specific regional cluster instead of gateway auto-selection:

• pass --issuer https://mcpcn.coros.com (cn), --issuer https://mcpeu.coros.com (eu), or --issuer https://mcpus.coros.com (us) to any login or tool command.
• this overrides gateway discovery.

if user asks to clear saved login state:

• run python3 scripts/coros_mcp_login.py logout only if user explicitly requests it. this deletes local token cache.

if a tool requires arguments that are not obvious from the schema:

• ask the user only for the missing required fields. do not dump the entire schema back to them.

if network timeout or temporary gateway outage occurs:

• retry the command after 30 seconds. the helper includes exponential backoff for transient failures.
• if gateway remains unreachable, check https://mcp.coros.com status page or ask user to verify network connectivity.

if oauth device code expires (typical 15 min window):

• the helper will prompt the user to run login-start again for a fresh device code.
• no manual state cleanup is needed.

output contract

on successful login (apply-openclaw):

• stdout: "mcp entry 'coros' created" or "mcp entry 'coros' refreshed"
• stdout: "gateway resolved to <cn|eu|us> cluster" (if helpful to user)
• stdout: "login reused from cache" or "fresh login completed"
• file: ~/.coros-mcp-skill-gateway//token.json (contains non-printable access token)
• file: ~/.coros-mcp-skill-gateway//token_info.json (metadata: expires_at, scopes, issuer)
• exit code: 0

on successful list-tools:

• stdout: json array of {name, description} objects
• example: [{"name": "queryUserInfo", "description": "..."}, ...]
• exit code: 0

on successful describe-tool:

• stdout: json schema object (inputSchema, required fields, types)
• exit code: 0

on successful call-tool:

• stdout: json response from mcp server
• exit code: 0

on any error:

• stderr: sanitized error message (no token values, no passwords, no sensitive paths)
• exit code: 1

outcome signal

the skill worked if all of the following are true:

1. login phase: user ran apply-openclaw (or login-start + login-finish) and saw no auth errors. if prompted for browser login, user was able to open the link and complete coros login without credential rejection.

2. openclaw registration: running openclaw mcp show coros returns a non-empty config with issuer, server-name, and endpoint fields.

3. tool discovery: running list-tools returns a non-empty json array of tool objects (not an error).

4. tool execution: running call-tool on a simple tool (e.g., queryUserInfo with empty args {}) returns valid json response from the mcp server (not a 401, 403, or connection error).

5. region confirmation (optional but helpful): if the user cares about which regional cluster was selected, the helper printed "gateway resolved to <cn|eu|us>" or the issuer in token_info.json matches the expected region.

6. state persistence: if the user runs the same command again without re-logging in, the helper uses the cached token (stdout shows "login reused from cache"), proving the session persists across invocations.

7. user report: you tell the user plainly:

   • whether mcp entry was created or refreshed
   • whether fresh login or cached login was reused
   • which regional cluster the gateway selected (if relevant)
   • whether tool catalog and sample tool call both succeeded
   • if any manual next step remains (e.g., "you can now call tool X with these args")