Onbid Public Auction MCP

A read-only MCP that lets you query the official public data APIs of the Korea Asset Management Corporation's Onbid from Codex. It uses a BYOK (Bring Your Own Key) approach in which each user enters their own public data portal service key directly.

Bidding, login, electronic signature, deposit payment, and payment features are not included. Search results are for candidate discovery; before an actual bid, you must directly verify the original Onbid notice and attached documents, the appraisal report, the registry, possession and rights relationships, and whether there have been the latest corrections or cancellations.

Provided Tools

• check_onbid_api_key: Check the current API key and list API access permission

• get_onbid_codes: Guide to representative search codes

• search_onbid_properties: Search properties by region, price, area, ownership share, number of failed auctions, etc.

• get_onbid_property: View property details, lease and registry summaries, possession, and cautions

• search_onbid_results: Search bid results by period, such as winning bid price and number of bidders

1. Applying for Public Data Portal APIs

Each user must apply for each of the APIs below with a public data portal account. All are marked as free and automatically approved, but operating agency policies may change.

1. Next-generation Onbid real estate property list inquiry service

2. Next-generation Onbid real estate property details inquiry service

3. Next-generation Onbid real estate bid results list inquiry service

Prepare the general authentication key issued from the public data portal My Page. Whichever of the Encoding or Decoding key you enter, the installation script normalizes it once.

2. Quick Installation on Windows

Run in Power Shell:

git clone https://github.com/XamTE/onbid_mcp.git
powershell -ExecutionPolicy Bypass -File .\onbid_mcp\scripts\install.ps1

The script receives the API key as masked input, verifies it with a single call to the list API, and then does the following:

• Stores the Windows user environment variable ONBID_SERVICE_KEY

• Adds the XamTE/onbid_mcp GitHub marketPlace

• Installs the onbid-public-auction plugin

After installation, fully restart the Codex app. To skip API verification, you can add - SkipValidation.

Manual Installation and Other Operating Systems

First set ONBID_SERVICE_KEY as a user environment variable, then run:

codex plugin marketplace add XamTE/onbid_mcp --ref main
codex plugin add onbid-public-auction@xamte-onbid

You must restart the Codex app or terminal for the environment variable to be read. Do not put the key in command-line arguments or a Git repository.

Updates and Removal

codex plugin marketplace upgrade xamte-onbid

To remove the plugin and the API key environment variable together on Windows:

powershell -ExecutionPolicy Bypass -File .\scripts\uninstall.ps1

Add - KeepApiKey to keep the key.

API Key Handling and Privacy

Codex sends the API key from the local environment variable as the Bearer token for remote MCP requests. This server uses the key only while processing a request to call the public data portal API and does not store it in a database or logs. Response caching and request interval control are separated per user by a SHA-256 fingerprint, not by the raw key.

Since ordinary request metadata may be processed on Vercel and across the network path, refer to PRIVACY.md for details. This structure does not guarantee that the key is never exposed in a public deployment, so if you need stronger control, deploy this repository yourself or run the MCP locally.

Call Volume and Performance

• Limits upstream calls from the same user to a minimum start interval of 150 ms.

• Caches identical requests in memory for 1 minute for lists and 5 minutes for details and results.

• Coalesces concurrent identical requests into one.

• Retries network errors and 5xx only once; authentication and quota errors are not retried repeatedly.

• The maximum page size is 100, and result periods span at most 366 days per request.

Operate based on the daily traffic limits shown on each API page for public data portal development accounts. If multiple PCs or automation share the same key, the limits are combined. Even for personal use, avoid unnecessary repeated searches and large-scale page traversal at short intervals.

Local Development

npm install
npm run check
npm run dev

When testing authenticated MCP requests locally, use the Authorization: Bearer <본인 서비스 키> header. Do not put the key in .env or in commits.

Deployment

After deploying to Vercel, point the URL in plugins/onbid-public-auction/.mcp.json to your actual /api/mcp address. No server public API key is required.

License and Responsibility

The source is distributed under the MIT license. Each user must verify the terms of use of the public data and the policies of Onbid and the public data portal, and this tool does not guarantee investment returns or the legal or physical condition of properties.