Oms Client Agent

This project exposes the OMS client as a local MCP server over stdio.

How it works

The MCP host starts this server as a local stdio process. The agent calls the exposed MCP tools, and the server translates those tool calls into OMS Wallet SDK calls.

Email sign-in is a two-step flow: oms_start_email_auth sends the OTP to the email address from the user prompt, then oms_complete_email_auth completes the auth attempt with the OTP code. Those two calls need to run in the same server process.

After sign-in, wallet session metadata and the credential signer key are persisted in the platform secure store. That lets a later MCP process restore the wallet session and sign messages or transactions without exposing secrets to the agent.

Token transfers are intentionally narrow. ERC20 transfers use wallet.callContract with transfer(address,uint256), and native token transfers use wallet.sendTransaction with only to and value fields.

Configure

Run setup:

pnpm run setup:mcp

This creates .env from .env.example if it does not already exist, builds the local Keychain helper, and prints the Codex MCP config block for this checkout.

Then fill in .env:

OMS_PUBLISHABLE_KEY=...
OMS_PROJECT_ID=...

Wallet session data, redirect auth state, and the Node credential signer key are stored in macOS Keychain under fixed oms-client-agent-mcp:* service names.

On Linux, the same values are stored through Freedesktop Secret Service using secret-tool. Install libsecret-tools and ensure a Secret Service provider such as GNOME Keyring or KWallet is available and unlocked.

Example Prompts

Sign in

Sign in using [email protected]

Wait for response, then enter OTP code:

123456

Send USDC

Send 1 USDC to 0xB54d0b73a40f5b9a243D142EeDDA39Bb5ed76B50 on amoy

Get token balances

What's my USDC balance on Polygon mainnet?

Run

If you skip pnpm run setup:mcp, build the local Keychain helper once:

pnpm build:keychain-helper

Then run the MCP server:

pnpm --silent mcp

The check and test scripts compile src/storage/keychain-helper.swift to bin/keychain-helper before running. The mcp script expects that binary to already exist so MCP stdout stays protocol-clean.

Example MCP host config:

{
  "mcpServers": {
    "oms-client-agent": {
      "command": "pnpm",
      "args": ["--silent", "mcp"],
      "cwd": "/Users/theirname/path/to/oms-mcp"
    }
  }
}

Tools

• oms_env_status: checks required environment keys without printing secrets.
• oms_session_status: reports whether a wallet session is restored.
• oms_start_email_auth: sends an email OTP to the email address provided in the tool call.
• oms_complete_email_auth: completes the OTP flow in the same server process.
• oms_sign_message: signs a message with the active wallet session.
• oms_get_token_balances: queries token balances through the OMS indexer.
• oms_get_native_token_balance: queries the native token balance.
• oms_send_erc20_token: sends ERC20 tokens through wallet.callContract using transfer(address,uint256).
• oms_send_native_token: sends native tokens through wallet.sendTransaction.
• oms_sign_out: clears the active wallet session.

Default network is amoy. Pass a supported SDK network name such as polygon, base, or sepolia where tools accept network.

Transfer tools accept raw integer amounts: amountRaw for ERC20 base units and amountWei for native token wei.