ICON MCP v101

You deploy and use this MCP Server to access ICON MCP v101 endpoints through a standardized interface. It supports authenticated access with a client API key or pay-per-use access via a built-in HTTP 402 protocol, making it suitable for AI agents and LLMs to interact with ICON MCP v101 securely and efficiently.

How to use

Connect your MCP client to the server’s /mcp endpoint to call ICON MCP v101 tools. You can operate in two modes: authenticate with your own ICON MCP v101 API key for free access, or pay per request if you do not have a key. In authenticated mode, your client’s API key is passed and the server forwards requests to ICON MCP v101 on your behalf. In paid mode, you submit payment proof and the server validates it before returning results.

From a client perspective, you obtain an API key from ICON MCP v101 for authenticated access, or you prepare a payment payload following the HTTP 402 flow to enable paid access. Use the server’s HTTP endpoint to call tools like example_tool, and handle responses in your application as you would with any MCP-enabled tool.

How to install

Prerequisites: you need Docker or Docker Compose, or you can run the server locally using Python with the uv tool as described. Ensure you have a suitable environment for your deployment choice.

Using Docker (recommended): clone the project, set your API key, and start the server with the provided script.

Using Docker Compose: prepare a .env file with your configuration values, then start the services with docker-compose up.

Manual installation (Python with uv): install dependencies and run the server with the environment variable for the API key.

Configuration and security

Two operational modes are supported. Authenticated access uses your ICON MCP v101 API key and does not require payment. Paid access uses the server’s internal API key and verifies payments via the D402 integration. Keep your private keys and API keys secure and never expose them in client-side code.

Environment variables you may configure include the server’s internal API key, the server’s payment address, operator keys for signing settlement attestations, and optional testing mode flags for local development. Use these values only in secure server environments.

Deployment notes

The server is designed to run in containerized environments and supports Cloud Run deployment. Deployment configuration includes the server name, description, and capabilities list. When you add tools, update the capabilities array accordingly and ensure the deployment parameters reflect the current tool set.

Troubleshooting

If the server does not start, inspect container logs for errors. Authentication issues typically indicate a missing or invalid API key. For API errors, verify the API key permissions. For tool errors, check server logs for detailed error messages tied to specific tool calls.

Available tools

example_tool

Placeholder tool (to be implemented)