optimus-mcp

Read-only Model Context Protocol server for Optimus Labs. Add it to your AI agent (Claude, Cursor, …) to query your organization's agentic inventory, security findings, and shadow-AI discovery signals directly from the agent — the same data you see in the Optimus console, scoped to your organization and your role.

This adapter is a thin transport: it holds a token and forwards typed requests to the Optimus API over HTTPS. All authorization, tenant isolation, auditing and rate limiting are enforced by the backend.

Tools

| Tool | Returns | | --- | --- | | list_filter_values | Agents, owners, resource types and endpoint ids actually present in the org. | | list_inventory | Agents, MCP servers and skills with owner, scope, approval status. Filters: scope, resource_type, approval_status, agent, owner, endpoint_id, q, page, per_page (max 1000). | | get_resource | One inventory resource by catalog uuid or numeric id. | | list_findings | Active findings with severity and state (state carries suppression). Filters: severity, states, agent, owner, level, search, page, per_page (max 100). | | get_finding | One finding by numeric id or formatted id (e.g. PERM-001). | | get_discovery_signals | Shadow-AI signals as strong_signals / weak_signals / ignored_signals. | | get_owner_rollups | Per-org totals: resources, approved/unapproved, unique owners. |

All tools are read-only.

Setup

1. In the Optimus console, an org admin mints an MCP token under Settings → MCP tokens (starts with optmcp_). It is shown once — copy it then.
2. Add the server to your agent's MCP config:

{
  "mcpServers": {
    "optimus-labs": {
      "command": "npx",
      "args": ["-y", "optimus-mcp-staging"],
      "env": {
        "OPTIMUS_MCP_TOKEN": "optmcp_your_token_here",
        "OPTIMUS_ENDPOINT": "https://app.optimuslabs.io"
      }
    }
  }
}

Environment

| Variable | Required | Description | | --- | --- | --- | | OPTIMUS_MCP_TOKEN | yes | Your optmcp_ Bearer token. | | OPTIMUS_ENDPOINT | yes | Your Optimus base URL, e.g. https://app.optimuslabs.io. |

The token must be supplied through the OPTIMUS_MCP_TOKEN environment variable (the env block above). Passing it any other way is unsupported — the server refuses to start if a token is given on the command line, because arguments leak into process listings (ps) and shell history.

Security

• The token is scoped to the issuing user's organization and role, and can be revoked at any time from the console.
• Every read is recorded in the Optimus audit log.
• The token is transmitted only over TLS (the adapter refuses a non-HTTPS OPTIMUS_ENDPOINT outside localhost) and is never logged by this adapter.
• Every tool advertises readOnlyHint / destructiveHint: false, so your client can confirm — not just read in prose — that these tools only read.

Publishing

There is no repo CI for npm. A maintainer with publish rights on the package runs this locally from this directory (after npm login to the right npm account):

npm ci
npm run build
npm publish --access public

Do not set "provenance": true in package.json — that expects CI OIDC and breaks a normal laptop publish.