action1-mcp-server

🚀 Quick start

1. Install

pip install action1-mcp-server

2. Get your API credentials

In Action1, go to Settings → API Credentials → Add API Credentials, assign the Viewer role, and copy the Client ID (an api-key-...@action1.com address) and the Client Secret. The secret is shown only once.

3. Connect your AI client

{
  "mcpServers": {
    "action1": {
      "command": "action1-mcp-server",
      "env": {
        "ACTION1_CLIENT_ID": "api-key-...@action1.com",
        "ACTION1_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

claude mcp add action1 -e ACTION1_CLIENT_ID=api-key-...@action1.com -e ACTION1_CLIENT_SECRET=your-client-secret -- action1-mcp-server

codex mcp add action1 --env ACTION1_CLIENT_ID=api-key-...@action1.com --env ACTION1_CLIENT_SECRET=your-client-secret -- action1-mcp-server

[mcp_servers.action1]
command = "action1-mcp-server"

[mcp_servers.action1.env]
ACTION1_CLIENT_ID = "api-key-...@action1.com"
ACTION1_CLIENT_SECRET = "your-client-secret"

The data center region (North America, Europe, UK, Australia) is detected automatically on the first login. To pin it, set ACTION1_REGION.

Updating

pip install --upgrade action1-mcp-server

Restart your AI client afterwards. Your configuration stays the same.

💬 What you can ask

Ask in plain language, in any language:

• "List the Action1 routes and what each one returns"
• "Give me an overview of the environment: endpoints, missing patches and vulnerabilities"
• "Which endpoints need a reboot or haven't checked in for more than 30 days?"
• "Show endpoint FINANCE-LAPTOP01 with its missing updates and CVEs"
• "List the critical CVEs in the CISA KEV catalog and which endpoints have them"
• "Which critical updates are past their SLA?"
• "How did last Friday's patch automation go on each endpoint?"
• "Who logged in to the console this week?"

📦 Available data

All routes below were tested against a live Action1 account with a Viewer credential.

Parameters, fields, required permissions and quirks for each route are documented in ENDPOINTS.md (in Portuguese). The map was built from Action1's official OpenAPI 3.1 specification, published at app.action1.com/apidocs.

🧰 Tools

Tool names are in Portuguese; your AI assistant picks the right one from your request. In Action1, an endpoint is a managed computer, so the tools call computers máquinas and API paths rotas.

The resource action1://rotas exposes the full API map as Markdown.

{
  "endpoint": "vulnerabilities/{orgId}",
  "params": {
    "score": "Critical",
    "remediation_status": "Overdue",
    "filter": "Chrome",
    "sortby": "-cvss_score"
  },
  "paginar": true,
  "max_registros": 500
}

🚦 Limits and behavior

🔒 Security

• Read-only. The server only sends GET requests; the one exception is the internal POST /oauth2/token login. Three GET routes are also blocked, even with permitir_nao_listados=True: the agent installer link, the Deployer installer link and remote sessions.
• Use a Viewer credential. The server's blocklist is a second layer; the role on the credential is the first. A Viewer key can't change anything even if a request gets through.
• Secret handling. The Client ID and Secret are read only from the environment, never written to logs, and the secret and tokens are removed from every response and error message.
• Audited. Every API call, including GETs, shows up in Action1's Audit Trail under the credential's user.
• Real company data. The credential sees your whole fleet, so conversations may contain hostnames, IP and MAC addresses, logged-on user names and vulnerability details. Request only what you need and follow your company's data protection policy.
• One credential per person. Never share the secret in chat, e-mail or GitHub issues. If it leaks, revoke it in Settings → API Credentials right away.

📥 Other installation methods

Requires Python 3.10 or newer.

🛠 Development

Local setup

git clone https://github.com/jpedrocrc/Action1-MCP-Server
cd Action1-MCP-Server
pip install -e .

With -e, code changes take effect without reinstalling; just restart your AI client. To switch back to the published version, run pip uninstall -y action1-mcp-server, then pip install action1-mcp-server.

[!NOTE] The package requires mcp<2. Version 2.x of the mcp SDK renamed FastMCP, and the server has not been migrated yet.

Tests

python test_server.py --offline

Runs without network access. It checks the API map, tool registration, pagination (against simulated responses) and the safeguards (blocked routes, GET-only code, secret and token masking).

python test_server.py

Needs ACTION1_CLIENT_ID and ACTION1_CLIENT_SECRET. It calls every mapped route with limit=2, reuses the IDs it finds to test routes that need one, then calls every tool. Routes the credential's role can't reach are reported as SEM PERMISSÃO, not as failures. It takes about 1 minute.

To try the server in the MCP Inspector (requires uv and npx), run the command below and set ACTION1_CLIENT_ID and ACTION1_CLIENT_SECRET under Environment Variables before connecting:

mcp dev src/action1_mcp/server.py

📋 Changelog

📄 License

MIT © João Pedro Rodrigues