Skip to navigation
IntegrationsAI IntegrationsAdd AI Integrations

Add the Eon Local MCP Server

Who can use this feature

Anyone with these permissions: Manage API credentials

This article explains how to run the Eon local MCP server, so an AI tool can work with your Eon account without an interactive browser sign-in.

eon-mcp-local is a Python package that runs as a local process and communicates using the Model Context Protocol (MCP) over stdio. It signs in to the Eon API with API credentials instead of a browser, so it works where an interactive sign-in isn’t possible: CI pipelines, scripts, headless containers, and agent frameworks. It’s also the option to choose when you want to run the server process yourself.

Add the Eon local MCP server

Before you start

Before you start, make sure:

  • Python 3.12 or later is installed.

  • Either uv or pipx is installed. The examples here use uvx, which comes with uv.

  • You’ve decided which Eon role the AI tool should act with. An API client receives its permissions from the role assigned to its credentials, so the role has to cover everything you’ll ask the AI tool to do.

1

Create API credentials in Eon

  1. On the API credentials page, create a set of credentials and assign them the role you chose.

  2. Copy the client ID and the client secret.

    The client secret is shown only once, when you create the credentials. If you lose it, rotate the secret from the same page to get a new one.

The server acts as the API client rather than as you, and the role assigned to its credentials can let it start an on-demand snapshot, connect a source account, create a backup policy, or open an action request. Assign a role with only the permissions the AI tool needs.

2

Configure and start the server

Register eon-mcp-local with your AI tool as a stdio MCP server, and pass the Eon credentials to it as environment variables. The command is uvx eon-mcp-local serve, which fetches and caches the package on first run, so there’s nothing to install up front. serve is the only subcommand and it takes no flags, so all configuration comes from the environment.

Add the server with claude mcp add, passing the variables inline:

claude mcp add eon-local \
  --env EON_CLIENT_ID=<client-id> \
  --env EON_CLIENT_SECRET=<client-secret> \
  --env EON_ACCOUNT_DOMAIN=<subdomain> \
  -- uvx eon-mcp-local serve

These are the environment variables the server reads:

EON_CLIENT_ID
stringRequired

The client ID from the API credentials.

EON_CLIENT_SECRET
stringRequired

The client secret from the API credentials.

EON_ACCOUNT_DOMAIN
stringRequired

Your Eon subdomain on its own, not a full URL. For an account hosted at acme.console.eon.io, the value is acme.

EON_LOG_LEVEL
stringDefaults to INFO

How much the server logs: DEBUG, INFO, WARNING, ERROR, or CRITICAL. The value isn’t case sensitive.

EON_JSON_LOGGING
booleanDefaults to false

Set to true to write logs as JSON.

The server also reads a .env file from the directory it starts in, so you can keep these variables in that file instead of exporting them.

If you’d rather install the package than fetch it on each run, install it with uv tool install eon-mcp-local or pipx install eon-mcp-local, then use eon-mcp-local serve as the command.

Your AI tool now starts the server as a local process and signs in to Eon with the API credentials. An access token is valid for 12 hours, and the server keeps it in memory only, so it’s never written to disk.

To check that the connection works, ask your AI tool to list the tools available to it, then ask it something small, such as which backup jobs ran most recently. In Claude Code, you can also run /mcp to see the server’s status.

Troubleshooting

The server reports error: missing required environment variables when EON_CLIENT_ID, EON_CLIENT_SECRET, and EON_ACCOUNT_DOMAIN aren’t all set. Set all three in the AI tool’s server configuration, or in a .env file in the directory the server starts in.

Either the credentials are no longer active, or they belong to a different Eon account than the one in EON_ACCOUNT_DOMAIN. Check both on the API credentials page, and rotate the secret if you’re not sure the one you copied is still valid.

EON_ACCOUNT_DOMAIN takes your subdomain on its own, so a full URL such as https://acme.console.eon.io produces a name that doesn’t resolve. Set it to just the subdomain, such as acme.

The server writes all logs to stderr, because stdout carries the MCP protocol frames. Capture stderr separately from stdout, and set EON_LOG_LEVEL to WARNING or ERROR if you want fewer logs.

See also

Was this page helpful?