@marboba/mcp

@marboba/mcp — MarBoba Model Context Protocol server

Wraps the public MarBoba /v1 REST surface as MCP tools so any MCP-aware client — Cursor, Claude Code, GitHub Copilot, Cline, Windsurf — can read and update your MarBoba catalog inline while you code.

Auth uses a Personal Access Token (mb_pat_*); the same token shape the MarBoba CLI and the Terraform provider use.

What it exposes

30 read tools covering the whole catalog:

Resource	List	Get
Projects	list_projects	get_project
Teams	list_teams	get_team
APIs	list_apis	get_api, fetch_api_spec
Runbooks	list_runbooks	get_runbook
On-call	list_oncall_schedules	get_oncall_binding
Scorecards	list_scorecards	get_scorecard
SLOs	list_slos	get_slo
Resources	list_resources	get_resource
Systems	list_systems	get_system
Domains	list_domains	get_domain
Issues	—	get_issue
Deployments	—	get_deployment
Dependencies	list_dependencies	—
Drift	list_drift	—
Integrations	list_integrations	—
Scaffold templates	list_scaffold_templates	—
Secrets metadata (no values)	list_secrets	—
Agent actions	list_agent_actions	get_agent_run

Write tools

34 mutating tools cover the catalog CRUD surface, in two tiers:

Tier 1 — direct catalog writes. create_* / update_* / delete_* for projects, teams, APIs, resources, systems, domains, dependencies (create/delete only), issues, runbooks, on-call bindings, and SLOs. The /v1 API enforces your PAT's scope:

Operation	Required PAT scope
create_*, update_*, refresh_oncall_binding	write
delete_*	admin

Every write emits an audit-log row server-side, so mutations made through MCP are attributable exactly like UI or CLI changes.

Tier 2 — privileged actions. propose_agent_action opens an agent run (rotate-vault-secret, rollback-to-last-green, scale-service) that a different human approves in the web app's two-person flow. The MCP server never executes a privileged action directly — it can only propose one.

Token-management, billing, SSO, and the approve/reject side of the agent flow are intentionally out of scope.

Quick start

1. Get a Personal Access Token

In the MarBoba app: Settings → API Tokens → New token. Tokens look like mb_pat_live_AbCd... and inherit the scopes you grant. For read-only catalog access, the read scope is enough.

2. Add to your MCP client config

Claude Code

~/.claude/settings.json (or ~/.config/claude/settings.json):

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

Cursor

~/.cursor/mcp.json (or per-project .cursor/mcp.json):

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

Cline / Windsurf / Continue

These editors all read MCP servers from the same mcpServers block shape. Drop the same JSON into the editor's MCP config file.

3. Override the endpoint for self-hosted / dev / qa / staging

{
  "env": {
    "MARBOBA_API_TOKEN": "mb_pat_test_...",
    "MARBOBA_ENDPOINT": "https://api-dev.marboba.com"
  }
}

Defaults to https://api.marboba.com (prod).

Run it with Docker

For boxes without Node. The image speaks MCP over 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_..." }
    }
  }
}

Pin a version with :0.2.1 instead of the default :latest.

Install with Homebrew

Puts a marboba-mcp binary on PATH (still needs Node — use Docker for a Node-free box):

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

Then point your MCP client's command at marboba-mcp (no npx).

Try it without installing

If you're checking it out from this repo:

cd marboba-mcp
npm install
npm run build
MARBOBA_API_TOKEN=mb_pat_... node dist/index.js

The server speaks stdio. To exercise it from the command line without a real MCP client, send a list-tools JSON-RPC call:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | MARBOBA_API_TOKEN=mb_pat_... node dist/index.js

How it works

your editor → MCP client → stdio → marboba-mcp → /v1 REST → MarBoba

The server is one process per editor session. Stateless — every tool call hits /v1 fresh, so you never see a cached catalog. The PAT is only ever in-process; we don't write it to disk or forward it anywhere except the Authorization header on outbound calls.

Development

# Hermetic tests — no real network
npm test

# Watch mode for the test runner
npm run build -- --watch

The client.ts module is pure transport (uses an injectable fetchImpl). Every tool registered in src/tools/index.ts is a thin adapter from MCP shape → typed /v1 call.

Releasing

• Bump version in package.json.
• npm test && npm run build — ensure the suite is green.
• npm publish --access public.

The package is published as @marboba/mcp so customers can npx @marboba/mcp without thinking about the registry path.

Security

• Tokens are read from environment variables only — no config file.
• The server validates the token shape (mb_pat_*) and warns to stderr on mismatch, but lets the API decide if the token is actually valid.
• HTTPS-only by default; if MARBOBA_ENDPOINT is set to an http:// URL the request still goes (for self-hosted plain-HTTP clusters) but the standard PAT-leak risks apply.

License

MIT — see LICENSE.