# @aiotic/mcp

The [Model Context Protocol](https://modelcontextprotocol.io) server for the **AIOTIC** Integrator Guide. It gives your
coding assistant (Claude Code, Cursor, VS Code or any other MCP client) exact answers while you integrate AIOTIC
purchase-order processing with your ERP: it searches the guide, returns endpoint contracts and schemas from the public
OpenAPI document and hands out payload examples. On your own machine it can also look at your test tenant.

- **Documentation:** <https://developers.aiotic.ai/ai/mcp-server> — tools, security model, setup per assistant.
- **Changes:** [CHANGELOG.md](https://github.com/devopscompanynl/aiotic-mcp/blob/main/CHANGELOG.md).
- **Questions and problems:** open an issue in [this repository](https://github.com/devopscompanynl/aiotic-mcp/issues).

## Use it

The entry differs per assistant: Claude Code and Cursor read `mcpServers`, VS Code reads `servers`.

Claude Code, in `.mcp.json` in your project:

```json
{ "mcpServers": { "aiotic": { "command": "npx", "args": ["-y", "@aiotic/mcp"] } } }
```

Cursor, in `.cursor/mcp.json` in your project, or in `~/.cursor/mcp.json` for every project:

```json
{ "mcpServers": { "aiotic": { "type": "stdio", "command": "npx", "args": ["-y", "@aiotic/mcp"] } } }
```

VS Code, in `.vscode/mcp.json` in your project:

```json
{ "servers": { "aiotic": { "type": "stdio", "command": "npx", "args": ["-y", "@aiotic/mcp"] } } }
```

Other assistants and where their configuration lives: [MCP server](https://developers.aiotic.ai/ai/mcp-server) in
the guide. Node.js 20 or newer. There is nothing else to configure: docs mode needs no key and sends nothing anywhere.

Each version carries one edition of the guide and of the API document, so pin a version
(`"args": ["-y", "@aiotic/mcp@<version>"]`) when you want the same answers every time. The server reports the edition
to your client when it connects.

Prefer no installation at all? The hosted endpoint `https://mcp.aiotic.ai/mcp` runs the same server in docs mode and
always serves the latest revision of the guide. For Claude Code:

```json
{ "mcpServers": { "aiotic": { "type": "http", "url": "https://mcp.aiotic.ai/mcp" } } }
```

The guide has the entry, a one-line command or a one-click link for every other assistant:
[Connect your coding assistant](https://developers.aiotic.ai/ai/mcp-server#connect-your-coding-assistant).

## Docs mode (default)

| Tool | What it returns |
|---|---|
| `search_guide(query, limit?)` | Best-matching sections with page, heading and snippet |
| `list_pages()` | Every page of the guide with section, title and summary |
| `get_page(path)` | One page as Markdown |
| `list_endpoints(tag?)` | Method, path, summary and authentication per endpoint, plus the outbound webhooks |
| `get_endpoint(operationId \| "METHOD /path")` | The full contract: parameters, request and response schemas, examples |
| `get_schema(name)` | One schema from the OpenAPI components |
| `get_example(name)` | Payload samples |
| `get_status_lifecycle()` | Status values, their meaning and the transitions between them |

## Tenant mode (opt-in, local only)

Set `AIOTIC_BASE_URL` and `AIOTIC_API_KEY` in the server's environment and the assistant can also read your **test**
tenant or the mock from the [AIOTIC Python SDK](https://github.com/devopscompanynl/aiotic-sdk-python): orders and
their status, rejected e-mails, customers, products and customer item mappings.

```json
{ "mcpServers": { "aiotic": {
    "command": "npx", "args": ["-y", "@aiotic/mcp"],
    "env": { "AIOTIC_BASE_URL": "http://localhost:8080", "AIOTIC_API_KEY": "mock-integration-key" } } } }
```

That is the entry for Claude Code and Cursor; in VS Code the same `command`, `args` and `env` go under `servers`,
with `"type": "stdio"`.

- Read tools are on. Write tools need `AIOTIC_MCP_ALLOW_WRITES=true`. Deletes and `send_order_to_erp` also need
  `AIOTIC_MCP_ALLOW_DANGEROUS=true` and `confirm: true` in the call.
- Keys come from the environment, never from tool arguments, and are removed from everything the server returns.
- Tenant tools exist on the stdio transport only. Use a test tenant: whatever key you put in an assistant's
  environment, the assistant can use.

## Run it over HTTP yourself

```bash
npx -y @aiotic/mcp --http 3333      # http://127.0.0.1:3333/mcp and /healthz, docs mode only
```

The HTTP transport refuses to start when any tenant variable is set. Behind a reverse proxy, set
`AIOTIC_MCP_TRUST_PROXY` to the peers whose `X-Real-IP` and `X-Forwarded-For` headers may be believed: `1`
(loopback), `gateway` (the container's default gateway), `private`, CIDR ranges or `any`.

| Variable | Purpose | Default |
|---|---|---|
| `AIOTIC_MCP_HOST` | Address the server listens on | `127.0.0.1` |
| `AIOTIC_MCP_RATE_BURST`, `AIOTIC_MCP_RATE_PER_SECOND` | Requests per client address: a burst, then a steady rate | `60`, `1` |
| `AIOTIC_MCP_ALLOWED_HOSTS` | `Host` header allow-list | any host |
| `AIOTIC_MCP_ALLOWED_ORIGINS` | Browser origins that may call; a request with any other `Origin` gets 403 | none |
| `AIOTIC_MCP_MAX_BODY` | Largest request body, in bytes | `262144` |
| `AIOTIC_MCP_BLOCKLIST` | File with addresses and CIDR ranges to refuse | none |
| `AIOTIC_MCP_ANALYTICS_DIR` | Usage log, one JSON line per request; `node dist/stats.js --dir <dir> --days 30` aggregates it | off |
| `AIOTIC_MCP_RETENTION_DAYS` | Days the usage log is kept | `180` |
| `AIOTIC_MCP_LOG_DAY_MAX_MB`, `AIOTIC_MCP_LOG_MAX_MB` | Size limits of the usage log, per day and in total | `128`, `512` |
| `AIOTIC_MCP_GEOIP_DB` | MMDB country database for the usage log | none |

## Development

```bash
npm ci
npm test        # builds, then runs the smoke test over stdio and HTTP
```

This repository is published release by release from the AIOTIC documentation sources, one commit per release, and
each release is published to npm from here by `.github/workflows/publish-npm.yml`. Pull requests cannot be merged here
directly; please open an issue and we will take the change into the next release.

## License

MIT, see [LICENSE](https://github.com/devopscompanynl/aiotic-mcp/blob/main/LICENSE).