@min-ai/mcp-admin

An MCP server that lets a customer manage their minai instance from their own machine, through their own CLI agent.

Runs on the customer's machine, not in the platform. It talks to the public API with the customer's API key, so it holds no privileged position: everything it can do, curl with the same key could do. The key resolves to exactly one company inside core's tenantAuth — tenant isolation is not something this package enforces, it is something it cannot circumvent.

Distinct from @minai/mcp, which ships inside the runtime image and serves agents with the runtime token.

Setup

Two environment variables:

| var | value | |---|---| | MINAI_URL | the instance base URL, e.g. https://api.min-ai.ar | | MINAI_API_KEY | from Settings → Account in the dashboard (mnk_…) |

Wire it into Claude Code:

claude mcp add minai-admin \
  -e MINAI_URL=https://api.min-ai.ar \
  -e MINAI_API_KEY=mnk_key_… \
  -- npx -y @min-ai/mcp-admin

Codex and other MCP clients take the same command; the transport is stdio.

Working from a checkout of this repo instead of the published package:

  -- npx -y tsx /path/to/packages/mcp-admin/src/index.ts

Pair it with the skill, which teaches the domain model — agent versus session, how triggers work, the credential attach-vs-link split, and how to diagnose "it stopped working". The tools alone let an agent make calls; the skill is what stops it guessing.

The skill is not shipped in this package. Installing an npm package does not install a Claude Code skill — nothing in either system connects the two — so a skill/ directory in the tarball silently never arrived anywhere useful. It is served from the dashboard instead, with per-CLI install steps: Settings → Account → "See here", or /settings/cli-access.

Tools

Seventy-seven, covering everything the dashboard can write. They are shaped around the questions people actually ask rather than one per REST endpoint — a 1:1 wrapper would expose everything and leave the agent to work out which six calls answer one question.

Orientation — get_instance_overview (start here: company, runtime health, and every agent/workflow/channel/team/inbox in one call)

Agents — list_agents, get_agent, create_agent, update_agent, delete_agent

Resource library — list_resources (slugs agents can be given; pass a kind for full configuration), get_skill, create_skill, update_skill, delete_skill, create_repo, update_repo, delete_repo, validate_mcp_config, create_mcp_server, update_mcp_server, delete_mcp_server, get_script, create_script, update_script, delete_script, run_script

Workflows — list_workflows, get_workflow, get_workflow_runs, create_workflow, update_workflow, set_workflow_enabled, delete_workflow, fire_workflow

Webhooks — list_webhooks, create_webhook, update_webhook, delete_webhook, test_webhook

Channels & streams — list_channels, create_channel, update_channel, delete_channel, list_streams, create_stream, update_stream, delete_stream, manage_allowlist

Correspondence — list_inboxes, get_inbox, get_inbox_entry, create_inbox, update_inbox, delete_inbox, list_held_drafts, decide_held_draft, list_transports, create_transport, update_transport, delete_transport

Sessions — list_sessions, get_session_messages, control_session (stop / restart / recycle / expire)

Teams — list_teams, create_team, update_team, delete_team, set_team_membership

Plugins — list_plugins, get_plugin, install_plugin, reconcile_plugin (update / repair), uninstall_plugin

Credentials — list_credentials, set_credential (write-only; see below), update_credential (metadata, without rotating), list_credential_usages, delete_credential

Observability — get_activity, list_audit_actions, list_failed_deliveries (messages the platform gave up on — the answer to "it says it replied and nothing arrived")

Skills, repos, MCP servers, webhooks, inboxes and transports are addressed by slug, because a slug is what agents attach by and what the dashboard shows. The lookup to an id happens inside the tool, and a slug that doesn't exist gets named back along with the ones that do.

Deliberate limits

• No secret reads. Credential values are write-only in the API and encrypted at rest. list_credentials returns slugs, names and wiring. There is no endpoint that returns a value, so there is no tool that can. list_credential_usages is named list_, not get_, for that reason — it returns references to a credential, never anything from inside one.
• No shell. The API key is refused on the terminal WebSocket, so opening a shell in the runtime stays dashboard-only. run_script is the sanctioned way to execute something there.
• No platform administration. Creating companies, issuing runtime tokens and managing users are admin-only surfaces a customer key cannot reach.
• Paged reads are bounded (5 pages, 100 per page by default). An agent asking to "list the sessions" on a busy instance should not pull thirty thousand rows into its context. When the cap is hit the result says truncated: true so the agent narrows its query rather than silently reasoning over a partial list.

On destructive tools

The write surface is broad, and an API key has no scopes — anything this package can delete, any holder of the key can delete. Two things push back on that, neither of which is authorization:

• Every tool that removes something says DESTRUCTIVE in its description, with what it cascades to. A test enforces this.
• delete_agent additionally requires confirm: true, because it cascades to the agent's sessions and every message in them — for a support agent, the entire customer correspondence.

Scoped keys are the real answer and do not exist yet. Treat a key as equivalent to dashboard access.

Errors

API failures come back as tool results, not protocol errors, with messages written for an agent rather than a developer — a bare 401 says nothing about what to do differently. See explain() in src/client.ts.

A malformed MINAI_API_KEY fails at startup, not on the first call an hour later.