AIOTIC MCP server

AI-assisted integration

@aiotic/mcp is a Model Context Protocol server that gives your coding assistant precise access to this guide and the API contracts — and, if you opt in on your own machine, to your test tenant.

Hosted endpoint and npm package

The hosted endpoint https://mcp.aiotic.ai/mcp is live: no installation, no key, the docs-mode tools below. Connect your coding assistant with one click or one command. The package @aiotic/mcp is on npm: npx -y @aiotic/mcp runs the same server on your own machine, which tenant mode needs. The changelog announces each release.

Docs mode is public and read-only. Tenant mode is local-only and off by default.

Docs mode (default)

No keys, no tenant. The server ships with an index of the guide and the OpenAPI document.

Tool	What it returns
search_guide(query, limit?)	Best-matching sections with page, heading and snippet
get_page(path)	One page as Markdown (/receiving/erp-receive-endpoint)
list_pages()	Every page with path, section, title and one-line summary, in reading order
list_endpoints(tag?)	Method, path, summary, auth per endpoint (+ the outbound webhooks)
get_endpoint(operationId | "METHOD /path")	Full contract: parameters, request/response schemas, examples
get_schema(name)	One schema from the OpenAPI components (PurchaseOrder, ErpReceiveRequest, …)
get_example(name)	Payload samples (erp-receive-request, order-status, sync-events)
get_status_lifecycle()	Status values, meanings, transitions, sendable set

Connect your coding assistant

The hosted endpoint needs nothing installed, no account and no key. Every option below adds a server named aiotic that points at https://mcp.aiotic.ai/mcp.

One click

• Add to VS Code
• Add to Cursor
• Add to Kiro

Each link opens the editor, which shows the server and asks you to confirm before adding it. In VS Code the tools are then available to GitHub Copilot in agent mode.

One command

Claude Code

claude mcp add --transport http aiotic https://mcp.aiotic.ai/mcp

Codex

codex mcp add aiotic --url https://mcp.aiotic.ai/mcp

Copilot CLI

copilot mcp add --transport http aiotic https://mcp.aiotic.ai/mcp

Gemini CLI

gemini mcp add --transport http aiotic https://mcp.aiotic.ai/mcp

VS Code

code --add-mcp '{"name":"aiotic","type":"http","url":"https://mcp.aiotic.ai/mcp"}'

Kiro CLI

kiro-cli mcp add --name aiotic --url https://mcp.aiotic.ai/mcp --scope global

Configuration file

For assistants without a button or a command, and for configuration you keep in a repository, add the entry by hand.

Cursor · Kiro · JetBrains

{ "mcpServers": { "aiotic": { "url": "https://mcp.aiotic.ai/mcp" } } }

Claude Code

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

VS Code

{ "servers": { "aiotic": { "type": "http", "url": "https://mcp.aiotic.ai/mcp" } } }

Antigravity

{ "mcpServers": { "aiotic": { "serverUrl": "https://mcp.aiotic.ai/mcp" } } }

Windsurf

{ "mcpServers": { "aiotic": { "url": "https://mcp.aiotic.ai/mcp", "transport": "http" } } }

OpenCode

{ "mcp": { "aiotic": { "type": "remote", "url": "https://mcp.aiotic.ai/mcp" } } }

Assistant	Where the entry goes
Cursor	~/.cursor/mcp.json, or .cursor/mcp.json in a project
Kiro	~/.kiro/settings/mcp.json, or .kiro/settings/mcp.json in a project
JetBrains AI Assistant	Settings → Tools → AI Assistant → Model Context Protocol (MCP) → Add, then paste the entry
Junie	~/.junie/mcp/mcp.json, or .junie/mcp/mcp.json in a project
Claude Code	.mcp.json in a project
VS Code	.vscode/mcp.json in a project
Antigravity	~/.gemini/config/mcp_config.json, or .agents/mcp_config.json in a project
Windsurf	~/.config/devin/mcp_config.json. Versions from before Devin Desktop use ~/.codeium/windsurf/mcp_config.json, with serverUrl in place of url
OpenCode	opencode.json in a project, or ~/.config/opencode/opencode.json

Any other MCP client: point it at https://mcp.aiotic.ai/mcp with the Streamable HTTP transport.

Hosted endpoint

https://mcp.aiotic.ai/mcp runs the same server in docs mode only: stateless, no tenant tools, no secrets, always the latest published revision of this guide. The revision is reported to your client on connect (serverInfo.version, for example “revision 42”) and at https://mcp.aiotic.ai/healthz. Limits per client address: 60 requests at once, then one per second; beyond that the server answers HTTP 429 with a Retry-After header.

To operate the service and understand how it is used, every request is logged with the client address, the country derived from it, the MCP client name and version, the tool called and its arguments (for example the search text), timing and result size. Log entries are deleted after 180 days at the latest. Addresses that abuse the service can be blocked. Requests that carry a browser Origin header are refused: the hosted endpoint is for MCP clients, not for web pages; browser-based tools should run the package locally.

Local package

@aiotic/mcp runs the same server on your own machine (Node.js 20 or newer); tenant mode needs it. Add it to your assistant's configuration:

Claude Code · Cursor

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

VS Code

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

Tenant mode (opt-in, local only)

Lets the assistant look at your test tenant or the mock while you develop: "why is order X in ATTENTION?", "do we have product 620206_01 in AIOTIC?".

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

Tool	Default
tenant_health, get_order_status, list_orders, get_order_group, list_rejected_emails, get_customer, search_customers, list_products, get_product, list_customer_products	on (read-only)
upsert_customer, upsert_product, upsert_customer_product, upload_order, retry_order, reprocess_rejected_email	off — AIOTIC_MCP_ALLOW_WRITES=true
delete_*, send_order_to_erp	off — additionally AIOTIC_MCP_ALLOW_DANGEROUS=true and confirm: true in the call

Rules the server enforces:

1. Tenant tools exist only on the stdio transport. The HTTP transport refuses to start with a tenant configured.
2. Keys come from environment variables, never from tool arguments, and are never included in any output or log line.
3. Every argument is schema-validated; responses are truncated to a bounded size; API responses are returned as data (the server never follows instructions found in them).
4. Nothing is cached across sessions; nothing is written to disk.

Use a test tenant

Point tenant mode at the mock or a test tenant. A production key in an assistant's environment is a production key in an assistant's environment.

Versions

The package embeds the guide index and the API document of the guide version it was published with, so what your assistant reads is exactly one published edition. npx -y @aiotic/mcp always fetches the latest; pin a version with npx -y @aiotic/mcp@<version> when you want reproducible answers. The hosted endpoint always serves the latest published revision. The first published version is announced in the changelog. The version is reported to your MCP client on connect.