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 Setup → MCP Server, selects that active token, and generates a setup prompt. Paste the prompt into your agent. The prompt contains a one-time redeem code, not the long-lived optmcp_ token. The agent POSTs the code to /api/mcp-server/v1/setup/redeem/ and writes the response to ~/.optimuslabs/mcp.env.
2. Do not put the token in MCP client JSON. That is a hardcoded secret — the same finding Optimus raises on customer configs. The client config should only reference the env file:

{
  "mcpServers": {
    "optimus-labs": {
      "command": "npx",
      "args": ["-y", "optimus-mcp-staging"],
      "envFile": "${userHome}/.optimuslabs/mcp.env"
    }
  }
}

The env file (~/.optimuslabs/mcp.env, mode 600):

OPTIMUS_MCP_TOKEN=optmcp_your_token_here
OPTIMUS_ENDPOINT=https://app.optimuslabs.io

If you are configuring by hand, generate a setup prompt and run the curl -o command it contains yourself, then add the JSON above. If the client does not support envFile, source the env file in the launch command — still never inline the token in JSON.

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 (from ~/.optimuslabs/mcp.env via envFile, not from inline JSON). 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.