Getting started

usmart-mcp is a local trading MCP server. It runs on your machine, uses local credentials and your uSMART authorization, and executes order queries, pre-trade checks and order placement on behalf of your AI client.

Before you start

• A uSMART account with SG OpenAPI access
• A client_id from an OAuth app on the developer platform (a public app — no client secret needed)
• Python 3.10–3.13 and uv
• An MCP client: the ChatGPT / Claude connectors, or Claude Code, Cursor, Codex, Kiro

1. Prepare the local credential directory

Credentials live only in ~/.usmart. They are never shipped with the package and never passed to the model as tool arguments.

~/.usmart/
├── config.json          # region, gateway, auth mode, limits
├── oauth_session.json   # written after authorization (600)
└── audit/               # JSONL audit trail for writes

On macOS and Linux, tighten the directory:

mkdir -p ~/.usmart && chmod 700 ~/.usmart

2. Configure OAuth2

{
  "region": "SG",
  "baseUrl": "https://open2-jy.usmartsg.com",
  "auth": {
    "mode": "oauth2",
    "oauth": {
      "baseUrl": "https://jy.usmartsg.com",
      "clientId": "<client_id from the developer platform>",
      "redirectUri": "http://localhost:5100/callback",
      "scopes": ["order:all"]
    }
  },
  "limits": { "enabled": true, "maxDailyOrderCount": 20 }
}

redirectUri must match the registered value character for character, and must be a loopback address (localhost, 127.0.0.1 or ::1).

3. Add it to a client and authorize

Local clients take one command — Claude Code here:

claude mcp add usmart -- uvx --from usmart-mcp==1.2.0 usmart-mcp

For ChatGPT and Claude, add the connector from the plugin directory or Connectors; the browser opens uSMART sign-in. Once authorized, check credentials first:

check_trade_credentials