🔌 An AI agent inside emoms: the MCP server

What it gives you

emoms has a built-in MCP (Model Context Protocol) server. The AI agent you already use connects to emoms, reads the built-in "how it works" guides, checks an order, the logs and the configuration, and then walks you through what to do. By default access is read-only. Writes to the ERP (product descriptions, photos, prices) are enabled separately on the "Configuration" tab and by default land in a review queue for your approval.

To do in emoms

1. Enable the server in configuration. In the emoms appsettings.json set "Mcp": { "Enabled": true } and restart emoms. The default port is 4999 (key Mcp:Port), listening only on the emoms machine. Leave "BindLan" at false and run the agent on the same machine: with true the port is visible on the local network, the token travels over it unencrypted, and anyone on the LAN can request a session. Changing the port or binding also requires a restart.
2. Settings → MCP server → "Status" tab: check "Enabled: True" and switch "Server running" on.
3. "Configuration" tab: set the token lifetime (1–72 hours, default 8) and click "Save".
4. Approve the session. When the agent asks for access, a row with the client name, purpose and IP address appears on the "Sessions" tab → "Pending sessions" (the list does not refresh itself, use "Refresh"). Approve only the session you have just triggered yourself and check the IP address; reject unknown ones (the name and purpose are supplied by the client). Click "Approve". The agent picks the token up once; after it expires it asks for a new session.

How the agent asks for a session

• POST http://localhost:4999/mcp/session/request with body {"name":"Claude","purpose":"order diagnostics"} returns sessionId.
• GET http://localhost:4999/mcp/session/<sessionId>/status returns the token (once) and expiresUtc after approval.
• Every call to http://localhost:4999/mcp carries the header Authorization: Bearer <token>.

Connecting a client (examples)

• Claude Code: claude mcp add --transport http emoms http://localhost:4999/mcp --header "Authorization: Bearer <token>"
• Claude Desktop (Windows, mcp-remote bridge, header via an environment variable because Claude Desktop on Windows breaks arguments with spaces): in claude_desktop_config.json: {"mcpServers":{"emoms":{"command":"npx","args":["-y","mcp-remote","http://localhost:4999/mcp","--header","Authorization:${AUTH_HEADER}"],"env":{"AUTH_HEADER":"Bearer <token>"}}}}
• Gemini CLI: in ~/.gemini/settings.json: {"mcpServers":{"emoms":{"httpUrl":"http://localhost:4999/mcp","headers":{"Authorization":"Bearer <token>"}}}}
• Codex CLI: in ~/.codex/config.toml a section [mcp_servers.emoms] with url = "http://localhost:4999/mcp" and the token via bearer_token_env_var = "EMOMS_MCP_TOKEN" (syntax per the current Codex docs).
• ChatGPT: connectors require a public HTTPS address with OAuth sign-in and cannot reach a local emoms. Do not expose emoms or the MCP port to the internet; use Codex CLI on the emoms machine.

What to ask the agent

"Read emoms://system-map and explain how to set up a carrier." "Why does order 12345 have no invoice?" "How do I enable the Allegro auto-reply?" The agent reads the resources emoms://shop-messaging, emoms://shipping-setup, emoms://shop-account-setup, emoms://known-pitfalls-* and answers from the real configuration of your installation.