@marboba/mcp — MCP server

The @marboba/mcp server exposes the public /v1 REST surface as MCP tools so any MCP-aware client (Cursor / Claude Code / Copilot / Cline / Windsurf) can read your MarBoba catalog inline while you code.

Install

Most MCP clients invoke the package via npx:

{
  "mcpServers": {
    "marboba": {
      "command": "npx",
      "args": ["-y", "@marboba/mcp"],
      "env": {
        "MARBOBA_API_TOKEN": "mb_pat_live_..."
      }
    }
  }
}

Drop this into your MCP client’s config — ~/.claude/settings.json, ~/.cursor/mcp.json, the Cline / Windsurf / Continue equivalents.

Optional: set MARBOBA_ENDPOINT if your platform team has given you a non-production URL to test against. (Non-prod URLs aren’t published — ask your team.)

Docker

For environments without Node. The image speaks stdio, so run it with -i:

{
  "mcpServers": {
    "marboba": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MARBOBA_API_TOKEN", "ghcr.io/somexai-applications-group/marboba-mcp"],
      "env": { "MARBOBA_API_TOKEN": "mb_pat_live_..." }
    }
  }
}

Homebrew

brew install SomexAI-Applications-Group/marboba/marboba-mcp

Puts a marboba-mcp binary on PATH — point your client’s command at it instead of npx. (Still needs Node; use Docker for a Node-free box.)

The server exposes 30 read tools and 34 write tools. Reads need the PAT’s read scope; writes are scoped per operation (see Write tools below).

Read tools

fetch_api_spec

Fetch the live OpenAPI / AsyncAPI / GraphQL schema for an API by id. Returns the raw spec content + format. Use this when the LLM needs to call the API and wants endpoint shapes.

get_agent_run

Fetch a single agent run by id — status, approver, action, payload, audit trail.

get_api

Fetch a single API by id with owner, spec format, and metadata.

get_deployment

Fetch a single deployment by id with status, app, environment, build artifact, and timestamps.

get_domain

Fetch a single domain by id.

get_issue

Fetch a single issue (bug / feature / task) by id with its full activity stream.

get_oncall_binding

Fetch a single on-call binding by id with the full rotation schedule.

get_project

Fetch a single project by id, with full catalog detail (owner team, on-call binding, scorecard summary, environments, dependencies). Use this when the user names a specific project or after list_projects narrows the choice.

get_resource

Fetch a single resource by id.

get_runbook

Fetch a single runbook by id with the full markdown body, linked apps, and execution metadata. Use this when the user identifies a specific runbook to read or follow.

get_scorecard

Fetch a single scorecard by id with the full check list.

get_slo

Fetch a single SLO by id with full metric history.

get_system

Fetch a single system by id with its full membership list.

get_team

Fetch a single team by id with full member + ownership detail.

list_agent_actions

List the agent actions registered in this org (rotate-vault-secret, scale-service, rollback-to-last-green, etc) — what they do, blast radius, approval requirements.

(no parameters)

list_apis

List every API in the org’s catalog (REST/GraphQL/gRPC/AsyncAPI). Returns id, name, owner, spec format, and link to the live OpenAPI/AsyncAPI spec. Use this when the user asks ‘what APIs are there’, ‘where’s the auth API’, or wants to discover endpoints to call.

(no parameters)

list_dependencies

List every cross-component dependency edge in the catalog. Useful for impact analysis.

(no parameters)

list_domains

List business domains — top-level groupings of systems (e.g., ‘Payments’, ‘Identity’).

(no parameters)

list_drift

List drift snapshots — places where deployed config has diverged from what the catalog says it should be.

(no parameters)

list_integrations

List every third-party integration the org has connected (GitHub / GitLab / Bitbucket / Slack / Jira / etc).

(no parameters)

list_oncall_schedules

List every on-call binding for the org — which team or person is on-call for each project, the rotation cadence, and current+next on-call. Use this when the user asks ‘who’s on-call for X’ or ‘who do I page’.

(no parameters)

list_projects

List every project (app/component/resource) in the org’s MarBoba catalog. Returns id, name, internalCode, platform, environments, and lifecycle. Use this when the user asks ‘what projects do we have’, ‘show me everything in the catalog’, or before drilling into a specific project.

list_resources

List infrastructure resources (databases, queues, buckets, secrets-vaults). Returns id, kind, owner team, environment, and links to the underlying cloud resource.

(no parameters)

list_runbooks

List every runbook in the org. Returns id, title, runbookType (incident/deployment/rollback/etc), linked apps, and severity links. Use this when the user is dealing with an outage or asks ‘what’s our runbook for X’.

(no parameters)

list_scaffold_templates

List project scaffolding templates available in this org (org templates + first-party catalog).

(no parameters)

list_scorecards

List every scorecard in the org (production-readiness, security, reliability, etc) with their checks and per-project pass/fail counts.

(no parameters)

list_secrets

List vault secrets metadata (NEVER values — names, environments, last-rotated, expiry only).

(no parameters)

list_slos

List every SLO in the org with target, error budget, and current burn rate.

(no parameters)

list_systems

List logical systems — collections of projects + APIs + resources that ship together (e.g., ‘Checkout’, ‘Auth Platform’).

(no parameters)

list_teams

List every team in the org. Returns id, name, members, and the projects each team owns. Use this when the user asks ‘who owns X’ or ‘which team handles Y’.

(no parameters)

Write tools

The write surface mirrors the product’s safety model in two tiers. The /v1 API enforces your token’s scope on every call, and every write records an audit-log row attributing the change to your token.

Tier 1 — direct catalog writes

create_* / update_* / delete_* for the catalog. create and update need the write scope; delete needs admin.

On-call also has refresh_oncall_binding (re-resolves the schedule against the provider; write scope).

IDs are passed as tool parameters; only the fields you supply are changed. Required fields and enums match the REST API.

Tier 2 — privileged actions

propose_agent_action (write scope) opens an agent run for a privileged production action — rotate-vault-secret, rollback-to-last-green, or scale-service. It never executes the action directly: a different person approves it in the web app’s two-person flow — the AI can propose a production change, but a human still approves it.

See also

• REST API — the underlying surface the MCP tools wrap.
• marboba CLI — same /v1 surface, different shell.