MCP Server

Athena has a built-in Model Context Protocol (MCP) server. Any MCP-compatible client can connect to it to read and operate your fleet: agents and inventory, commands, deployments, collections, compliance, monitoring, reports, users, settings and remote tools. There is no extra service to install and no extra port to open. The client signs in as a real Athena user, gets that user’s permissions, and every tool call is written to the audit log.

What you need#

You don’t need to switch anything on. The MCP server is available whenever the license includes it. To control who can use it, grant or remove mcp.use on a role.

The address clients connect to#

The MCP endpoint is /mcp on the web console port:

https://athena.example.local:8443/mcp

• Transport: MCP Streamable HTTP. Configure your client for an HTTP (remote) MCP server and use the URL above. The server is stateless, so clients need no session affinity.
• Port: the web port, 8443 by default (Server:WebPort). If you changed that port, use your port instead. See Network Ports & Firewall.
• Not on the agent port. The agent port (8444 by default, also used through the Agent Gateway) returns 404 for /mcp. MCP clients must reach the web port.
• TLS: the endpoint uses the same HTTPS certificate as the console. The client machine must trust it. See Server TLS Certificate.
• Server identity: during the handshake, the server identifies itself as Athena Endpoint Platform. The version it reports is the same build version shown on the About page.

Authenticating#

An MCP client authenticates the same way as a REST client: it sends a bearer credential on every request. Use an API token (ath_…). Unlike a sign-in session, a token survives server restarts and has its own expiry, and you can revoke it on its own. Configure your client to send either header:

Authorization: Bearer ath_…
# or
X-Athena-Api-Token: ath_…

A short-lived session token from POST api/auth/login (see API Reference) also works. However, it expires on the session clock, and a server restart can sign it out (see Sessions & Server Restarts). That makes it a poor fit for a client you leave configured.

Create a token for the client in the console#

1. Sign in as the account the client should act as. Consider a dedicated service account whose role holds only what the client needs.
2. Click your initials badge in the top bar, choose Profile, and in the API Tokens panel click New token.
3. Give it a recognisable name and a lifetime. If you limit it to selected permissions, include mcp.use and the permissions for the tools the client needs.
4. Copy the token when it is shown. It is displayed only once.

Or create it with PowerShell#

# A read-only client: may open an MCP session and read agents, nothing else
New-AthenaApiToken -Name "mcp-client" -Permission mcp.use,agents.view

A token never holds more than its owner. Each call is checked against the owner’s current role, plus the token’s scope if it has one. A token limited to selected permissions that does not list mcp.use cannot connect. For lifetime limits, revoking and the admin view of every token, see API Tokens.

Connection responses#

What a client can do#

The server publishes a catalogue of tools named athena_…. They cover the same operations as the console and the REST API. Each tool is marked as read-only or not, and as destructive or not, so the client can tell reads apart from changes.

A client only sees the tools it may call. The tool list is filtered by the account’s permissions (and the token’s scope). A client never learns that a tool outside its permissions exists, and calling one directly is refused. The usual license rules also apply inside every tool. For example, on a lapsed license a tool that would start new work returns the same license message the console shows, ending with “Upload a current license file under Settings to restore it.” On a lapsed license (as opposed to one that never included the feature), the MCP server stays available, so read-only tools keep working.

Confirmation on high-impact tools#

MCP clients cannot be prompted by the server, so Athena guards high-impact tools with a required confirm argument instead. The client must pass back the target’s own identifying value, which it can only know by reading the target first. A mismatch, or a missing value, means nothing happens. Letter case and spaces at the start or end are ignored. Anything else must match exactly.

A wrong or missing confirmation is refused with a message such as:

Refusing to delete this agent: the 'confirm' argument must exactly match the target's own
identifying string (its hostname, username or name, depending on the tool). Read the target
first and pass the value it reports back.

The refusal deliberately does not include the expected value, so it cannot be copied from the error. Each tool’s description tells the client which value to pass.

Secrets stay on the server#

Before a tool returns a result, Athena removes secret values from it. Fields whose names end in password, secret, token, passphrase, private key, API key, secret key, signing key or server key are replaced, as are connection strings, password and token hashes, BitLocker PINs and similar values. They appear as "[redacted]" (or as an empty value when they are not text). Fields that only say whether a secret is set, such as “password set”, are kept.

A tool returns a secret only when that is the whole point of the tool:

• Revealing a vault secret works only for credentials of type Secret, needs credentials.reveal and a confirm, and is audited. Local and Domain account passwords are never revealed. See Credentials.
• Creating an API token or minting a registration token returns the new token once, just like the console does.

Audit trail and monitoring#

Every tool call, successful or not, writes one McpToolInvoked event to the audit log. No tool can skip it.

• Arguments are never recorded. They can contain passwords, file contents and other secrets. The event records who called which tool and whether it worked.
• The effects are audited too. A tool that changes something writes the same audit events as the console would. For example, deleting an agent through MCP also produces the usual agent events, under the same user.
• When the client uses an API token, the usual token events (ApiTokenUsed, ApiTokenAuthFailed) are also recorded. See API Tokens.

To review MCP activity, open the Audit Log and filter on the event type McpToolInvoked (see Filtering by event type). If you scrape Athena’s Prometheus metrics, the counter athena_mcp_tool_calls_total counts tool calls labelled by result: ok, error or denied (refused by the license or a credential or package permission check).

Troubleshooting#

Recommended practices#

• Connect each client with a dedicated service account whose role holds only what the client needs. Disabling that account stops the client at once.
• Give each client its own API token, limited to mcp.use plus the permissions it needs. Start with view permissions only.
• Grant mcp.use to a role only when its members actually connect MCP clients.
• Review McpToolInvoked events regularly, or forward them to your SIEM with Audit Forwarding.