@aiotic/mcp
# @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).
TDQS
Scored across 28 tools
Most tools have clearly distinct resource/action targets, but the documentation/reference cluster (get_schema, get_example, get_endpoint, list_endpoints, get_page, search_guide) has enough conceptual overlap that an agent could occasionally pick the wrong retrieval tool. Customer/product/order CRUD and lifecycle tools are otherwise well separated.
Almost all tools consistently use snake_case verb_noun or verb_resource patterns (list_products, get_customer, upsert_product, delete_customer_product). The main minor deviation is tenant_health, which is noun-based rather than action-based.
At 28 tools, the surface is heavy for a single MCP server and exceeds the 25-tool threshold where tool count becomes cumbersome. While some breadth is justified by combining live API operations with documentation/reference tools, the set is still large enough to burden selection.
The server covers the core customer, product, customer-product, order, rejected-email, ERP-send, and documentation workflows with create/read/update/delete or equivalent lifecycle operations. Minor gaps remain, such as no explicit list_customers or get_customer_product tool, and bulk operations appear in schemas but are not surfaced as tools.