JPYC Agent MCP skill

Use this skill when the task is specifically about operating JPYC Agent MCP through Codex or Claude Code.

Claude Code authentication

Claude Code does not auto-handle OAuth for streamable-http MCP servers. If the JPYC Agent MCP tools are not available as native MCP tools, use the helper script to call tools through the Bash tool:

# Check authentication
powershell.exe -ExecutionPolicy Bypass -File scripts/jpyc_oauth_cache.ps1 auth-status

# Call any tool
powershell.exe -ExecutionPolicy Bypass -File scripts/jpyc_oauth_cache.ps1 call-tool -Tool <tool_name> -Arguments '<json>'

If the user has not authenticated yet, guide them through:

1. scripts/jpyc_oauth_cache.ps1 start -OpenBrowser (Windows) or scripts/jpyc_oauth_cache.py start --open-browser (macOS/Linux)
2. Open the authorization_url in a browser and grant consent
3. scripts/jpyc_oauth_cache.ps1 wait -AuthSessionId <id> to save the token

For the full setup guide, see docs/claude-code.md.

Goals

• Keep the workflow inside the JPYC Agent MCP tool surface.
• Prefer read-only inspection before any state-changing action.
• Enforce quote-first sequencing for transfers and contract writes.
• Make missing prerequisites explicit before you attempt risky actions.

Tool scope

This skill is for these tool families:

• Authentication: auth_status
• Wallets: list_agent_wallets, get_agent_wallet, create_agent_wallet, get_agent_wallet_balance
• Transfers: quote_transfer, transfer_jpyc, list_transactions, get_transfer_status
• Contracts: read_contract, quote_contract_write, execute_contract_write, list_contract_call_history, get_contract_call_status

Do not invent tools or assume direct signer access, private keys, or backdoor admin capabilities.

Operating rules

1. Start by checking whether the user is authenticated when the task depends on private wallet data.
2. For wallet-oriented tasks, prefer list_agent_wallets before creating a new wallet.
3. Before any transfer or contract write, gather enough context to avoid avoidable failures:

• identify the wallet
• check available balance when relevant
• confirm chain assumptions are Polygon

1. Treat state-changing actions as two-step flows:

• transfer: quote_transfer -> transfer_jpyc
• contract write: quote_contract_write -> execute_contract_write

1. If the user asks for execution immediately, still obtain the quote first and summarize the quote before execution.
2. If the user request is ambiguous, prefer inspection and ask for the missing operational parameter rather than guessing.

Safe defaults

• Prefer agent_wallet_id over fuzzy identification when the user already has it.
• If there are multiple wallets and the target is unclear, stop and ask which wallet to use.
• When reading a contract, confirm the contract address, ABI fragment, method, and arguments before calling.
• When quoting a transfer, confirm to_address and amount_jpyc.
• When quoting a contract write, clearly distinguish estimation from execution.

Response guidance

• Summarize the current step and why it is needed.
• For state-changing requests, explicitly say that you are using a quote-first flow.
• If authentication or approval is required, say so plainly instead of implying execution succeeded.
• If the client does not surface a full OAuth authorization URL, tell the user to open https://jpyc-info.com/mcp/connect as the canonical human fallback.
• Only fall back to https://jpyc-info.com/api/jpyc-agent-oauth/start plus auth-session polling when the client needs a low-level manual OAuth flow for debugging or compatibility reasons.
• If repeated browser logins are a problem on Windows, prefer the local refresh-token helper at scripts/jpyc_oauth_cache.ps1 (PowerShell) or scripts/jpyc_oauth_cache.py (Python) and the workflow documented in docs/local-token-cache.md.
• Keep blockchain jargon to the minimum needed for the task.

What not to do

• Do not suggest bypassing OAuth, approvals, or quote validation.
• Do not ask the user for secrets or private keys.
• Do not present a quoted action as if it were already executed.
• Do not use this skill for unrelated Web3 tooling outside the JPYC Agent MCP endpoint.