JPYC Agent MCP

JPYC Agent MCP can be used both as a public MCP endpoint and as a Codex plugin bundle. This repository now uses the repository root as the plugin root so Codex can discover it directly.

What It Supports

Polygon agent wallet creation and lookup
Wallet balance inspection
JPYC transfer quote and execution flows
Contract read calls
Contract write quote and execution flows
Transfer and contract call status tracking

Plugin Layout

Codex should discover the plugin from the repository root via the files below:

Public Endpoint

MCP endpoint: https://jpyc-info.com/api/jpyc-agent-mcp
OAuth issuer: https://jpyc-info.com/api/jpyc-agent-oauth
Resource metadata: https://jpyc-info.com/.well-known/oauth-protected-resource
Authorization server metadata: https://jpyc-info.com/.well-known/oauth-authorization-server
OpenID configuration: https://jpyc-info.com/.well-known/openid-configuration
Human sign-in page: https://jpyc-info.com/mcp/connect
MCP Registry auth file: https://jpyc-info.com/.well-known/mcp-registry-auth

The endpoint is OAuth-protected. Users must log in and grant consent before private wallet operations can run. If you open the MCP endpoint directly in a browser, it redirects to https://jpyc-info.com/mcp/connect. If an MCP client receives 401 unauthorized, it should follow WWW-Authenticate and the resource metadata above to discover the OAuth flow. If ChatGPT/Codex does not surface a full authorization URL automatically, open https://jpyc-info.com/mcp/connect in the browser as the canonical human fallback. Low-level manual auth with /api/jpyc-agent-oauth/start remains available for debugging, but it is not the primary documented path. Clients using the low-level flow must keep the returned auth_session_secret private and present it when polling /api/jpyc-agent-oauth/auth-session.

For the complete OAuth contract and exact URLs, see docs/auth.md and config/oauth.json.

Claude Code

Claude Code does not natively support streamable-http MCP servers. Use mcp-remote to bridge streamable-http + OAuth to stdio.

Quick Start

Add the following to your project .mcp.json or ~/.claude/settings.json:

config.json

{
  "mcpServers": {
    "jpyc-agent-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://jpyc-info.com/api/jpyc-agent-mcp"
      ]
    }
  }
}

On first connection, mcp-remote opens a browser for OAuth consent. After authentication, all tools are available immediately.

Client Token Persistence

This repository defines the OAuth-protected MCP endpoint and the plugin metadata needed for Codex discovery. It does not implement client-side credential storage on behalf of Codex, ChatGPT, or any other MCP client.

Expected client behavior:

Start the OAuth flow against the JPYC Agent OAuth issuer
Receive the issued bearer token or equivalent session credential
Persist that credential in the client's local secure storage
Reuse it on subsequent MCP calls to https://jpyc-info.com/api/jpyc-agent-mcp
Verify the recovered session with auth_status

If a client can complete browser login but cannot persist and reuse the issued credential locally, the MCP integration is incomplete from the user's point of view. In that case, the fix belongs in the MCP client implementation rather than this repository's server-side OAuth protocol.

For local operator workflows, this repository includes helpers that persist the issued refresh token with DPAPI and reuse it across future sessions:

docs/local-token-cache.md
scripts/jpyc_oauth_cache.py (Python, Windows)
scripts/jpyc_oauth_cache.ps1 (PowerShell, Windows)

MCP Registry

This repository includes server.json for publishing the remote server to the public MCP Registry using the domain-based namespace com.jpyc-info/jpyc-agent-mcp.

For HTTP-based domain verification, host the exact text value v=MCPv1; k=...; p=... at https://jpyc-info.com/.well-known/mcp-registry-auth. In the jpyc-info deployment, that endpoint is served from the MCP_REGISTRY_AUTH environment variable.

Main Tools

auth_status
list_agent_wallets
get_agent_wallet
create_agent_wallet
get_agent_wallet_balance
quote_transfer
transfer_jpyc
list_transactions
get_transfer_status
read_contract
quote_contract_write
execute_contract_write
list_contract_call_history
get_contract_call_status

Detailed request and response examples are in docs/tools.md.

Recommended Flow

Check auth_status
Inspect wallets with list_agent_wallets
Create a wallet only if needed with create_agent_wallet
Check balances before transfers
Use quote-first execution for transfers and contract writes

Transfer flow:

quote_transfer
transfer_jpyc

Contract write flow:

quote_contract_write
execute_contract_write

Notes

This repo does not include secrets.
This repo does not include private keys or signer material.
The bundled skill is intended to keep Codex inside the JPYC Agent MCP tool surface.
For more details, see docs/auth.md, config/oauth.json, and docs/openai-and-mcp.md.