tossinvest-openapi-mcp

Safe-by-default local stdio MCP server for the official Toss Securities / 토스증권 Open API.

This package is an independent developer tool and is not affiliated with, endorsed by, or sponsored by Toss Securities.

This package is designed for developers who want read-only account, market, and order data in an MCP client, with optional order operations protected by multiple explicit safety gates.

Safety defaults

• Uses only the official Toss Open API server: https://openapi.tossinvest.com

• Starts without credentials; auth_status reports missing configuration instead of crashing.

• Keeps OAuth access tokens in memory only.

• On eligible GET 401 invalid-token or 401 token-revoked responses, replaces the affected cached token and retries once; concurrent issuance is shared within a client instance.

• auth_status separates token issuance from data endpoint reachability and reports whether a default TOSS_ACCOUNT_SEQ is configured.

• Redacts API keys, secrets, bearer tokens, account headers, and account numbers from tool output/errors.

• Trading is disabled by default.

• v0.2 workflow tools are safety-first and preview-based: portfolio_snapshot → pre_trade_check → order_preview → approval → order_execute → order_status_summary.

• order_preview stores preview contracts in memory only and never calls Toss order POST endpoints.

• order_execute is intentionally fast: it rechecks only preview/confirmation/hash/env/delegated-authority gates, submits at most one order POST, and reports timeout/network ambiguity as unknown_execution_state for reconciliation before any manual retry.

• Order tools default to dryRun=true.

• Real create/modify/cancel operations require ENABLE_TRADING=true plus the operation-specific gate.

• Confirmation is required by default.

• Default max order amounts are 0 KRW and 0 USD.

• BLOCKED_SYMBOLS takes precedence over ALLOWED_SYMBOLS.

Related MCP server: tossinvest-mcp

Install and run

This repository is currently distributed from GitHub source only. It has not been published to npm under an EthanKlocked-owned package.

Important: the unscoped npm name tossinvest-openapi-mcp is already used by a different npm package, so do not install or run that package expecting this repository's code.

Clone this repository, then install and build locally:

git clone https://github.com/EthanKlocked/tossinvest-openapi-mcp.git
cd tossinvest-openapi-mcp
npm install
npm run build
npm test

Run locally:

TOSS_API_KEY=... TOSS_SECRET_KEY=... node dist/index.js

Do not put real secrets in committed files. Prefer passing env vars from your local shell or MCP client secret manager.

MCP client configuration example

Use the local cloned path:

{
  "mcpServers": {
    "tossinvest": {
      "command": "node",
      "args": ["/absolute/path/to/cloned/tossinvest-openapi-mcp/dist/index.js"],
      "env": {
        "TOSS_API_KEY": "${TOSS_API_KEY}",
        "TOSS_SECRET_KEY": "${TOSS_SECRET_KEY}",
        "TOSS_ACCOUNT_SEQ": "${TOSS_ACCOUNT_SEQ}"
      }
    }
  }
}

If this project is later published to npm, use a package name owned by the maintainer, such as @ethanklocked/tossinvest-openapi-mcp, rather than the already-taken unscoped name.

Environment variables

Confirmation text for real order operations:

I understand this may place a real Toss Securities order

Tools

Read-only tools:

• auth_status

• accounts

• holdings

• prices

• orderbook

• trades

• price_limits

• candles

• stock_info

• stock_warnings

• exchange_rate

• market_calendar

• orders_open

• orders_closed

• order_detail

• buying_power

• sellable_quantity

• commissions

Workflow tools:

• portfolio_snapshot — reads holdings, KRW/USD buying power, open orders, calculable position weights, account/accountSeq state, warning flags, and partial failures. Position weights use a KRW-converted, cash-inclusive denominator (holdings + KRW/USD cash buying power); when cashStatus is partial, omitted cash currencies are listed in omittedCashCurrencies.

• pre_trade_check — separate read/check layer for candidate orders; returns canProceedDryRun, realOrderBlockedByDefault, checks, warnings, blockers, missing, estimate, and dataFreshness.

• order_preview — creates an in-memory preview contract; returns previewId, requestHash, ttlSeconds, expiresAt, exact confirmationText, estimated amount/fee/cash/quantity checks, gate status, risk flags, and calculability notes. It never calls order POST endpoints. Default TTL: 90 seconds; max accepted TTL: 300 seconds.

• order_execute — fast preview-based submission; requires previewId, matching requestHash, exact confirmation (I approve this exact Toss order preview), unexpired preview, env gates, and optional delegated-authority bounds. It does not run pre_trade_check in the hot path and does not add automatic order POST retry.

• order_status_summary — read-only reconciliation summary for open/recently closed orders, state counts, filled/partial/canceled/rejected/replace-related states when present, and caveats for disappeared/replaced orders.

Trading tools:

• order_validate — checks local gates only and never calls Toss order POST endpoints.

• order_create — defaults to dry-run; real execution requires all create gates.

• order_modify — defaults to dry-run; real execution requires all modify gates.

• order_cancel — defaults to dry-run; real execution requires all cancel gates. When ALLOWED_SYMBOLS or BLOCKED_SYMBOLS is configured, real cancellation also requires caller-supplied request.symbol so local symbol policy can be evaluated before the POST. The server does not fetch order details before cancel because this would add a second API dependency and the official detail payload shape should be confirmed by users with live credentials before relying on it for safety.

Auth status and account selection

auth_status intentionally separates OAuth token issuance from actual data API reachability:

• configured: required credential environment variables are present.

• tokenAvailable: POST /oauth2/token succeeded.

• dataApiReachable: a real read-only data check against GET /api/v1/accounts succeeded.

• authenticated: true only when both token issuance and the data endpoint check succeed.

• accountSeqConfigured: true when TOSS_ACCOUNT_SEQ is set.

• accountSeqRequiredForAccountTools: true; account-scoped tools need either a per-call accountSeq or TOSS_ACCOUNT_SEQ.

Most market-data tools such as prices, orderbook, trades, and stock_info do not require accountSeq. Account-scoped tools such as holdings, orders_open, orders_closed, order_detail, buying_power, sellable_quantity, commissions, and real/dry-run order tools require accountSeq via the tool arguments or TOSS_ACCOUNT_SEQ.

Token recovery and diagnostics

Token recovery matches exact structured code or error.code values (invalid-token, token-revoked) on HTTP 401 only. When present, error.code takes precedence even if unrelated or conflicting; the top-level code is used only when the nested code is absent (for example, an error object containing only message). Messages, arbitrary nested strings, and unrelated 401 errors do not trigger issuance. GET requests permit at most one authentication retry; a second rejection is returned as an API error. Existing POST invalid-token retry behavior is preserved, but POST token-revoked is never replayed. The internal retryInvalidToken: false option disables both authentication recovery codes, including order execution paths that already opt out. Ambiguous order outcomes still require reconciliation, not automatic replay.

Tokens remain memory-only, using expires_in with the existing 30-second expiry margin (and existing 60-second minimum lifetime / 3600-second default). Concurrent cold starts and refreshes share one in-flight issuance per client instance. Cache generations use object identity, so a late rejection cannot discard a newer generation even if the provider returns the same token string. This does not coordinate separate processes or external clients. There is no periodic issuance or refresh-token grant.

auth_status adds tokenLifecycle when credentials are configured: a snapshot of the latest issuance attempt, not proof of data API acceptance. Existing status fields remain; use dataApiReachable / dataApiCheck to check data access, including repeated token rejection.

• reason: cold-cache, expiry-margin, invalid-token, or token-revoked.

• startedAt, completedAt, expiresAt: Unix epoch milliseconds; completion/expiry can be null while pending or when unavailable.

• durationMs: elapsed issuance milliseconds, or null while pending.

• outcome: pending, succeeded, or failed.

Diagnostics contain only these fixed categories and timing values, never tokens, credentials, headers, provider bodies, or raw network messages. Issuance failures return a safe actionable configuration/network error; a later request can try issuance again. No new environment variables or required tool arguments are introduced.

After updating source, run npm run build and restart the MCP subprocess to load the new build. Deployment and read-only verification in the consuming environment are separate operator steps; source tests do not prove that runtime has been upgraded.

Endpoint mapping

v0.2 workflow examples

Recommended safety-first flow:

portfolio_snapshot → pre_trade_check → order_preview → user/delegated approval → order_execute → order_status_summary

Market calendar checks are routed by request market:

• currency=KRW or a six-digit Korean stock symbol uses market_calendar(KR).

• US tickers / currency=USD use market_calendar(US).

• US non-business days are detected from the official calendar shape when result.today.dayMarket, preMarket, regularMarket, and afterMarket are all null.

• KR non-business days are detected when result.today.integrated is null.

• In those cases pre_trade_check and order_preview return a market_closed_non_business_day blocker with market, date, and nextBusinessDay; they do not report market_open_unknown in missing.

portfolio_snapshot example:

{
  "accountSeq": 1,
  "currencies": ["KRW", "USD"],
  "limit": 50
}

pre_trade_check example. This is a separate read/check tool and is intentionally not forced into order_execute's hot path:

{
  "accountSeq": 1,
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  },
  "delegatedAuthority": {
    "remainingAmount": 100000,
    "expiresAt": "2026-07-05T15:00:00.000Z"
  }
}

order_preview example. It never calls Toss order POST endpoints and returns previewId, requestHash, TTL, and exact confirmation text:

{
  "accountSeq": 1,
  "ttlSeconds": 90,
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  }
}

order_execute example. Copy the previewId, requestHash, and exact confirmationText from the preview response:

{
  "previewId": "preview_...",
  "requestHash": "<sha256-from-preview>",
  "confirmation": "I approve this exact Toss order preview"
}

If an order POST times out or returns an ambiguous network failure, order_execute returns status: "unknown_execution_state" and directs callers to reconcile with order_status_summary/order_detail before any manual retry. The server does not automatically retry order POSTs.

order_status_summary example:

{
  "accountSeq": 1,
  "symbol": "005930",
  "limit": 50
}

Trading safety examples

Dry-run validation:

{
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  }
}

Real create requires all of the following:

ENABLE_TRADING=true
ENABLE_ORDER_CREATE=true
REQUIRE_CONFIRMATION=true
MAX_ORDER_KRW=100000
ALLOWED_SYMBOLS=005930

And the tool call must include:

{
  "dryRun": false,
  "confirmation": "I understand this may place a real Toss Securities order",
  "request": {
    "symbol": "005930",
    "side": "BUY",
    "orderType": "LIMIT",
    "quantity": "1",
    "price": "70000",
    "currency": "KRW"
  }
}

Official endpoint mapping

The implementation is intentionally thin and maps tools to official Toss Open API paths:

• OAuth: POST /oauth2/token

• Market/account/order data: /api/v1/... paths from https://openapi.tossinvest.com/openapi-docs/latest/openapi.json

• Order create/modify/cancel: official /api/v1/orders POST paths only, guarded locally before any POST is attempted.

Development

npm install
npm test
npm run lint
npm run audit:prod

The required test suite uses Node's built-in test runner and mocked fetch calls. It does not require real Toss credentials and does not call live order endpoints.

Opt-in read-only integration smoke test

After configuring your own Toss credentials locally, you can run a safe read-only smoke test:

TOSS_API_KEY=... TOSS_SECRET_KEY=... npm run smoke:readonly

Optional account-scoped checks can use TOSS_ACCOUNT_SEQ, but the default smoke path only calls read-only tools that do not create, modify, or cancel orders: auth_status, accounts, and market_calendar. If TOSS_API_KEY or TOSS_SECRET_KEY is missing, the command exits successfully with a SKIP message and makes no Toss API request. Output is passed through the same redaction helpers used by the MCP server.

Timeout/retry policy

This server applies a configurable request timeout to OAuth, read-only calls, and order calls. GETs retain bounded transient retries: up to three for HTTP 429 and two for HTTP 502/503/504, with retry delays capped at 10 seconds. Authentication recovery is separately bounded to one retry as described above. POSTs do not receive transient retries or new token-revoked replay; existing invalid-token behavior and per-call opt-outs are unchanged. Never retry an ambiguous order outcome without reconciliation.

Release checklist

Before publishing or tagging a release:

1. Verify package ownership and name availability; do not publish the unscoped tossinvest-openapi-mcp name.

2. Run npm test, npm run lint, npm run audit:prod, and npm pack --dry-run.

3. Confirm the dry-run tarball includes only runtime files (dist/ JavaScript/declarations without source maps), scripts/smoke-readonly.mjs, README.md, LICENSE, .env.example, and package metadata.

4. Re-scan docs for secrets, account numbers, local paths, private workflow notes, or investment advice/automation claims.

5. Publish only after explicit maintainer approval.

Publication hygiene

• .gitignore excludes .env, .env.*, logs, coverage, node_modules, and build output.

• .npmignore excludes local env files, logs, coverage, internal handoff/QA notes, and local run artifacts.

• package.json files only publishes dist, public docs, .env.example, and changelog/security/license files.

Disclaimer

This software is not investment advice and does not implement trading strategy, rebalancing, optimization, or automated trading loops. Order tools can place real financial orders only when explicitly enabled and used with valid Toss credentials; use at your own risk.