OnimatorOnimator
Check price
Glossary

Onimator MCP Server

Last updated August 11, 2026

What is Onimator MCP server? The Onimator MCP server is the specific local HTTP endpoint Onimator exposes when you enable MCP integration in Global Settings. Claude Code and other MCP-compatible clients connect to this endpoint to control your Onimator install through natural language. It’s the concrete server implementation that sits underneath the general MCP protocol — the MCP protocol is Anthropic’s open specification for AI-tool communication; the Onimator MCP server is Onimator’s specific implementation of that protocol on your machine.

The server exposes itself at a local address on your PC (default 127.0.0.1 with a specific port). It only runs while Onimator is open. When Onimator closes, the server closes with it, and any MCP client trying to connect gets “server unavailable” responses until Onimator is back up.

How it’s exposed

The server runs on a defined local port with a specific endpoint path. Typical setup:

  • Address: 127.0.0.1 (localhost only by default)
  • Port: Configurable in Global Settings — check the MCP section for the specific port your install uses
  • Endpoint: /mcp
  • Authentication: Custom header (X-IGBot-Token) carrying the token you generated in Onimator
  • Transport: HTTP

Together, the connection URL that clients register looks like:

http://127.0.0.1:PORT/mcp

With the auth header pointing at whatever token Onimator’s Global Settings generated when you enabled MCP.

What the server exposes

Once connected, MCP clients can call the specific functions the Onimator MCP server implements. At minimum, it supports read operations:

  • List devices registered in your install
  • List accounts across those devices
  • List current Job Orders and their statuses
  • Read per-account configuration data

Write operations are gated by the access level you set in Global Settings — read-only mode blocks any change operations, full-access mode lets clients modify state. Which specific write operations are supported depends on your Onimator version; MCP integration is still expanding what it covers, so check with the dev team before assuming any specific write action is available.

Why it’s local-only by default

The server binds to 127.0.0.1 rather than 0.0.0.0, which means it only accepts connections from the same machine Onimator runs on. This is deliberate — MCP access to your Onimator install gives whoever holds the token full authority over your account fleet if you’re in full-access mode. Restricting the server to localhost eliminates the specific risk of a random internet client discovering your endpoint and hitting it with your token.

If you need to reach the MCP server from a different machine, the standard approach is running it through Ngrok Tunnel or a similar tunneling service that exposes 127.0.0.1 to the internet through a secure HTTPS URL. Don’t just bind the server to 0.0.0.0 and open your firewall — that removes the safety net without adding meaningful convenience.

Setup gotchas

Common issues operators hit when connecting clients to the Onimator MCP server:

Onimator not open. The server only runs while Onimator is running. If you start Claude Code with MCP registered but Onimator is closed, the connection fails silently. Every MCP client just sees an unresponsive server. Open Onimator first, then connect from your client.

Wrong port. The port is set in Global Settings. If you registered the client with a placeholder port that doesn’t match what Onimator’s actually using, no connection. Check Global Settings for the specific port your install runs on.

Expired or wrong token. Tokens can be regenerated in Global Settings, and regenerating invalidates the old one. If you regenerate and forget to update the token in your MCP client registration, the client sends the old token, the server rejects it, connection fails.

Client-scope mismatch. On Claude Code specifically, the `claude mcp add` command’s default scope is local (tied to the directory you ran it from). If your VS Code Claude Code extension is running from a different directory, it won’t see the registration. Use `–scope user` to register at user scope so it applies across every session regardless of directory.

VS Code extension using its own CLI copy. The Claude Code VS Code extension bundles its own Claude CLI, and that bundled CLI may not read from the same MCP config as your system CLI. If `claude mcp list` in your terminal shows the server as connected but `/mcp` in the VS Code chat doesn’t, you’re hitting this specific mismatch. Fix by pointing the extension at your system CLI through the `claudeProcessWrapper` setting.

Testing the connection

The fastest verification once you’ve registered the server is a read-only prompt:

Use the Onimator MCP server and list my devices, accounts, 
and current Job Orders. Don't create, edit, or delete anything.

If the server is connected and Onimator is running, the client returns your actual device/account/Job Order data. If not, you’ll see a connection error that tells you which specific thing is broken.

Security around the token

The token acts like a password. Anyone who obtains it can control your Onimator install through the MCP endpoint (subject to whatever access level you’ve set). Practical hygiene:

  • Don’t paste tokens in chat threads, screenshots, or public issues
  • Regenerate the token immediately if you accidentally expose it
  • Use read-only mode when testing new clients so exposure risk is bounded
  • Only switch to full-access once you trust the client and the connection channel

Regeneration is one click in Global Settings, so exposure incidents are recoverable — but only if you actually regenerate. Skipping that step leaves the exposed token valid until you eventually rotate it.

Where the server fits in the Onimator stack

The MCP server is the specific integration surface that opens Onimator to AI-assisted control. Without it, everything happens through Onimator’s GUI or through the OniHelper Suite’s bulk-management tools. With it, MCP-compatible AI clients can operate against the install through natural language, subject to the specific capabilities the server implementation supports and the access level you’ve granted.

It’s not a replacement for the GUI or the Suite — it’s an additional interface layer that suits specific workflows (asking Claude Code “show me every account that’s been quiet for 48 hours” is faster than opening the interface and filtering manually). Everything MCP does, you can also do through the standard interfaces. What MCP changes is the specific ergonomics for operations that benefit from natural-language expression.

  • MCP (Model Context Protocol) — The protocol spec the Onimator MCP server implements
  • Global Settings — Where MCP server settings (enable/disable, port, token, access level) live inside Onimator
  • Ngrok Tunnel — The tunneling service used when the MCP server needs remote access beyond localhost