Content
# gainium-mcp
An MCP (Model Context Protocol) server for [Gainium](https://gainium.io) — the crypto trading bot platform. Lets AI assistants manage your bots, deals, balances, and more through a standard MCP interface.
Detailed setup and connection documentation is available in [docs/using-gainium-mcp.md](docs/using-gainium-mcp.md).
## Quick Start
### 1. Get your API keys
Go to [Gainium API Settings](https://app.gainium.io/app/api) and create an API key pair.
### 2. Add to your MCP client
Add this to your MCP configuration (VS Code, Claude Desktop, etc.):
```json
{
"gainium-mcp": {
"command": "npx",
"args": ["-y", "gainium-mcp"],
"env": {
"GAINIUM_API_KEY": "<your-api-key>",
"GAINIUM_API_SECRET": "<your-api-secret>"
}
}
}
```
That's it. The server starts automatically when your AI assistant needs it.
This local stdio mode uses `GAINIUM_API_KEY` and `GAINIUM_API_SECRET` from the server process environment.
### Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| `GAINIUM_API_KEY` | Yes | — | Your Gainium API public key |
| `GAINIUM_API_SECRET` | Yes | — | Your Gainium API secret |
| `GAINIUM_API_BASE_URL` | No | `https://api.gainium.io` | API base URL |
| `GAINIUM_MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio`, `http`, `streamable-http`, `sse`, or `http-sse` |
| `GAINIUM_MCP_HOST` | No | `127.0.0.1` | Bind host for HTTP mode |
| `GAINIUM_MCP_PORT` | No | `3000` | Bind port for HTTP mode |
| `GAINIUM_MCP_HTTP_PATH` | No | `/mcp` | Streamable HTTP endpoint path |
| `GAINIUM_MCP_SSE_PATH` | No | `/sse` | Deprecated SSE GET endpoint path |
| `GAINIUM_MCP_MESSAGES_PATH` | No | `/messages` | Deprecated SSE POST endpoint path |
| `GAINIUM_OAUTH_ISSUER` | No | — | Authorization-server base URL. Setting this (with `MCP_INTROSPECTION_SECRET`, in HTTP mode) enables OAuth protected-resource mode |
| `GAINIUM_INTROSPECTION_URL` | No | `<issuer>/oauth/introspect` | Token introspection endpoint |
| `MCP_INTROSPECTION_SECRET` | No | — | Shared secret presented to the introspection endpoint (must match the auth server) |
| `GAINIUM_MCP_PUBLIC_URL` | No | derived from request | Public base URL used in the protected-resource metadata |
| `OPENAI_APPS_CHALLENGE_TOKEN` | No | — | When set, served as plain text at `/.well-known/openai-apps-challenge` for OpenAI Apps domain verification |
## Authentication Modes
`gainium-mcp` supports three deployment models:
- **Local stdio mode:** the MCP server reads `GAINIUM_API_KEY` and `GAINIUM_API_SECRET` from env vars.
- **OAuth 2.1 hosted mode (recommended for hosted/public):** the server acts as an OAuth protected resource. Clients (e.g. the Claude connector) obtain an access token from the Gainium authorization server and send it as `Authorization: Bearer <token>`. See [OAuth 2.1 hosted mode](#oauth-21-hosted-mode) below.
- **Header hosted mode (legacy/self-hosted):** each request sends `X-API-Key` and `X-API-Secret` headers so one shared server can serve many users.
In header/stdio mode, request headers take priority, falling back to `GAINIUM_API_KEY` / `GAINIUM_API_SECRET`. When OAuth mode is enabled, the Bearer token is required and the `X-API-Key`/`X-API-Secret` headers are ignored.
### OAuth 2.1 hosted mode
This is the mode used for the public `https://mcp.gainium.io/mcp` endpoint and the Anthropic Claude connector directory (which requires OAuth and forbids API-key headers).
Enable it by setting, in HTTP mode:
```bash
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_OAUTH_ISSUER=https://app.gainium.io # Gainium authorization server
export MCP_INTROSPECTION_SECRET=<shared-secret> # must match the auth server
export GAINIUM_MCP_PUBLIC_URL=https://mcp.gainium.io # this server's public URL
# optional, defaults to <issuer>/oauth/introspect:
# export GAINIUM_INTROSPECTION_URL=https://app.gainium.io/oauth/introspect
node dist/server.js
```
When enabled, the server:
1. Serves **OAuth Protected Resource Metadata** (RFC 9728) at
`/.well-known/oauth-protected-resource` and `/.well-known/oauth-protected-resource/mcp`,
advertising the authorization server.
2. Rejects unauthenticated MCP requests with **`401 Unauthorized`** and a
`WWW-Authenticate: Bearer resource_metadata="…"` header, so clients can discover
the auth server and run the OAuth flow (Dynamic Client Registration + PKCE).
3. Validates the Bearer access token on each request via the auth server's
**token introspection** endpoint, resolving it to the user's Gainium
`(apiKey, apiSecret)` and per-key restrictions (read/write, paper-only, single-bot),
which are still enforced server-side. Introspection results are cached briefly.
The local stdio path is unaffected by these variables.
## HTTP and SSE Mode
By default, `gainium-mcp` runs over stdio for MCP clients that spawn local processes. To run it as an HTTP server instead:
```bash
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_MCP_HOST=127.0.0.1
export GAINIUM_MCP_PORT=3000
node dist/server.js
```
When HTTP mode is enabled, the server exposes both transport styles:
- `GET|POST|DELETE /mcp` for the current Streamable HTTP transport
- `GET /sse` plus `POST /messages?sessionId=...` for deprecated HTTP+SSE clients
This makes one server process compatible with both modern MCP HTTP clients and older SSE-based integrations. In hosted mode, authenticate with OAuth (see [OAuth 2.1 hosted mode](#oauth-21-hosted-mode)) or, for self-hosted/legacy setups, send `X-API-Key` and `X-API-Secret` on each request.
## Available Tools (17)
As of v3.0.0 the toolset is consolidated: a single tool per operation, with a
`botType` / `dealType` / `action` discriminator instead of one tool per variant.
Every tool carries an MCP safety annotation — read-only tools set `readOnlyHint`,
write tools set `destructiveHint`.
### Bots
| Tool | Access | Description |
|---|---|---|
| `list_bots` | read | List bots by type (`dca`, `combo`, `grid`) with filters and field selection |
| `get_bot` | read | Get a single bot by id and type |
| `create_bot` | write | Create a bot (`dca`, `combo`, or `grid`) |
| `update_bot` | write | Update bot settings |
| `clone_bot` | write | Clone a bot with optional overrides |
| `manage_bot` | write | Lifecycle action: `start`, `stop`, `archive`, `restore`, `changePairs` |
### Deals
| Tool | Access | Description |
|---|---|---|
| `list_deals` | read | List deals by type (`dca`, `combo`, `terminal`) with filters |
| `get_deal` | read | Get a single deal by id and type |
| `create_deal` | write | Create a deal |
| `update_deal` | write | Update an active deal |
| `manage_deal` | write | Deal action: `close`, `addFunds`, `reduceFunds` |
### Backtest
| Tool | Access | Description |
|---|---|---|
| `run_backtest` | write | Run a backtest: `validate`, `estimate`, async, or sync (`request`/`requestSync` submit a job — not read-only) |
| `backtest_info` | read | List backtest requests or get one by ID |
### Discovery, Account & Market
| Tool | Access | Description |
|---|---|---|
| `discover` | read | Schema discovery for bot types and indicators |
| `get_account` | read | Balances, connected exchanges, supported exchanges, and global variables |
| `get_screener` | read | Cryptocurrency screener with market metrics |
| `manage_global_variable` | write | Global variable action: `create`, `update`, `delete` |
## Field Selection
All GET endpoints support the `fields` parameter for efficient payloads:
- **Presets**: `minimal`, `standard` (default), `extended`, `full`
- **Custom**: comma-separated dot-notation fields (e.g. `_id,uuid,settings.name,profit.total`)
Using `minimal` reduces payload size by ~85%.
## API Permissions
- **Read-only key**: read tools only (`list_*`, `get_*`, `discover`, `backtest_info`, `get_screener`, `list_presets`)
- **Write key**: all tools, including `create_*`, `update_*`, `clone_bot`, `manage_bot`, `manage_deal`, `manage_global_variable`, `apply_preset`, and `run_backtest`
- **Read-only directory connector** (`/mcp` with `GAINIUM_READONLY=true`, served at `mcp.gainium.io/read`): exposes and allows only the 9 `readOnlyHint` tools — `run_backtest` and all write tools are excluded
- **Token audience binding (OAuth mode)**: when `GAINIUM_MCP_PUBLIC_URL` is set, the server treats `<public-url><http-path>` as its RFC 8707 resource. An access token whose introspected `aud` is a *different* resource is rejected — a token minted for `mcp.gainium.io/read` can't be replayed against `mcp.gainium.io/mcp`, and vice versa. Tokens with no `aud` (legacy grants) are still accepted.
## Development
```bash
# Clone and install
git clone https://github.com/gainium/gainium-mcp.git
cd gainium-mcp
npm install
# Build
npm run build
# Run locally (for testing)
export GAINIUM_API_KEY=your_key
export GAINIUM_API_SECRET=your_secret
node dist/server.js
# Run in HTTP/SSE mode
export GAINIUM_MCP_TRANSPORT=http
export GAINIUM_MCP_PORT=3000
node dist/server.js
```
## Architecture
```
gainium-mcp/
├── src/
│ ├── server.ts # MCP server + tool definitions (stdio + HTTP/SSE transports)
│ └── gainium-client.ts # HMAC-authenticated HTTP client for Gainium API v2
├── dist/ # Compiled output (published to npm)
├── package.json
├── tsconfig.json
└── README.md
```
## License
MIT
