Connect your agent

Use the API as MCP tools from a coding agent.

Access is by invitation: join the waitlist at app.moonbounce.ai and sign up once you’re granted access. The API behind these tools is in early access and unstable: names and shapes change often, breaking changes are expected, and there are no compatibility guarantees.

Install the plugin (Claude Code)

The Moonbounce plugin installs the decisions skill and MCP server with sign-in. No key is bundled.

claude plugin marketplace add clavataai/moonbounce-plugins
claude plugin install moonbounce@moonbounce

In Claude Code, run /mcp → plugin:moonbounce:moonbounce → Authenticate. Invoke the skill with /moonbounce:decisions.

To update, run claude plugin update moonbounce@moonbounce. The MCP server moved to https://api.moonbounce.ai/mcp; https://app.moonbounce.ai/mcp keeps working, but the new URL is a separate sign-in, so if you signed in before, run Authenticate once more after updating. API keys work on both.

Sign in without the plugin (Claude Code)

In Claude Code, connect directly with the URL:

claude mcp add --transport http moonbounce https://api.moonbounce.ai/mcp

Then run /mcp in Claude Code, pick moonbounce, and choose Authenticate.

Cursor

For Cursor, add the server to .cursor/mcp.json (project) or ~/.cursor/mcp.json:

{"mcpServers":{"moonbounce":{"url":"https://api.moonbounce.ai/mcp"}}}

Sign in from Cursor’s MCP settings (Customize → MCP) when the server needs login, or with the Cursor agent CLI run agent mcp login moonbounce, which opens AuthKit in the browser. Sign-in from Cursor is new: the Cursor agent CLI is checked up to the sign-in page and token exchange, and the Cursor editor is not tested yet. For an API key, add "headers": { "Authorization": "Bearer ${env:MOONBOUNCE_API_KEY}" } to that server; the variable must be in Cursor’s environment.

What sign-in allows

Signing in opens AuthKit in your browser; if you belong to several teams, pick one. Back in your agent, the tools work as you in that team, with no key to copy.

In Claude Code, if Authenticate fails with “Dynamic Client Registration rejected”, remove the directly added server (claude mcp remove moonbounce); if you installed the plugin, disable its server in /mcp. Add the server with the sign-in service’s OAuth metadata pinned instead, then authenticate it through /mcp:

claude mcp add-json moonbounce '{"type":"http","url":"https://api.moonbounce.ai/mcp","oauth":{"authServerMetadataUrl":"https://essential-sparrow-47.authkit.app/.well-known/oauth-authorization-server"}}'

Team admins and members alike can do everything a key with decisions:develop and decisions:evaluate allows: create and refine decisions, run real and dry-run evaluations, read evaluations, preview, work with suggestions, review and send feedback.

Sign-in runs everything in Production. Evaluations and their usage are attributed to you; reviews and feedback are recorded as you on channel mcp. Test traffic needs an env:test key.

To switch teams, clear the server’s authentication in your client (/mcp in Claude Code), then authenticate again and pick the other team. Someone removed from a team loses access within about 60 seconds.

The key-based setup below is for CI, backends, and agents that run unattended. Keys work on /mcp and /v1.

Connect with an API key

The same operations are MCP tools at https://api.moonbounce.ai/mcp, authorized with the same API key. A tool needs the same scope as its operation, so give your agent a key with decisions:develop. Make it a production key when the agent should improve a live decision: suggestions and previews learn only from the key’s environment, and only production suggestions are ever accepted (Engines, keys and environments). For Claude Code, put this in your repository’s .mcp.json and start claude from a shell where MOONBOUNCE_API_KEY is exported:

.mcp.json

{
  "mcpServers": {
    "moonbounce": {
      "type": "http",
      "url": "${MOONBOUNCE_API_URL:-https://api.moonbounce.ai}/mcp",
      "headers": { "Authorization": "Bearer ${MOONBOUNCE_API_KEY}" }
    }
  }
}

If the Moonbounce plugin is also installed, disable plugin:moonbounce:moonbounce in /mcp so the agent uses the key-based server.

Codex and other agents

For Codex CLI, connect and sign in:

codex mcp add moonbounce --url https://api.moonbounce.ai/mcp
codex mcp login moonbounce

The Codex route has not yet been tested with Moonbounce. For a key-based Codex connection, export MOONBOUNCE_API_KEY before starting codex:

codex mcp add moonbounce --url https://api.moonbounce.ai/mcp --bearer-token-env-var MOONBOUNCE_API_KEY

Other MCP clients with OAuth sign-in should work over Streamable HTTP at https://api.moonbounce.ai/mcp; not all are tested. Clients can also send Authorization: Bearer <key>. Sign-in gives admins and members decisions:develop and decisions:evaluate in Production, including real and dry-run evaluations attributed to them. Test needs an env:test key; unattended agents and backends use keys. Disable any signed-in connection when using a key-based one.

Claude Code plugin users should not also install the skill with the CLI: that adds /decisions beside /moonbounce:decisions. Add the skill with Node.js 22.20 or later:

npx skills add clavataai/moonbounce-plugins --skill decisions

Optionally add -a cursor -a codex to select agents. For Skills CLI installs, run npx skills update to update. The route installs only the skill, not the MCP connection: it lands in .agents/skills/decisions (read by Cursor and Codex), plus .claude/skills/decisions when Claude Code is selected. A daily check installs it from the public repository with Skills CLI 1.7.4 into an empty project and confirms SKILL.md and its references are present. The Claude Code plugin install from GitHub was observed on 2026-10-28.

Tools

There is one tool per API operation, named by the snake_case of its operationId, except GET /health and the feedback export, which are HTTP only:

Area	Tools
Specs	hash_spec, register_structure, get_structure, list_decisions, list_structures
Engines	list_engines, get_binding, set_binding
Evaluation	evaluate, get_evaluation, list_evaluations
Feedback	submit_feedback, get_feedback, import_seeds
Review	list_review_items, get_review_item, mark_review_shown, submit_review, skip_review, add_review_reason, withdraw_review, change_review, get_review_item_configuration
Improvement	list_suggestions, generate_suggestion, get_suggestion, set_suggestion_status, preview, get_loop_status
Identity and usage	whoami, get_usage
Applying a suggestion	apply_suggestion fetches a suggestion and hands your agent the steps and the code diff to apply

list_decisions, list_structures and get_structure accept decisions:evaluate or decisions:develop. Reading evaluations, including their list, requires decisions:evaluate. evaluate with body.dry_run: true spends engine calls but stores only usage and returns a dry_ id that names nothing stored; omit Idempotency-Key.

Each tool takes the operation’s path and query parameters, plus a body for operations that send JSON. The API reference has the shapes.

What your agent does with them

Your agent works in your repository, so it does the parts of the loop that touch code. Moonbounce’s MCP server can’t write your files.

• Describe. Draft the spec from a description of the decision or from the code that makes it today, check it with hash_spec, and seed it with labeled examples through import_seeds (Describe a decision, Feedback).
• Improve. Ask for a suggestion with generate_suggestion, or list proposed ones with list_suggestions, and preview any change with preview (Suggestions and previews).
• Apply. apply_suggestion returns the suggestion with step-by-step instructions: check that your decision file still matches the version the suggestion was made from, apply the diff, set the weights pin, run the preview and confirm its hashes match, then open a pull request for you to review. Nothing ships until you merge.

Check the connection

curl -sS -X POST "https://api.moonbounce.ai/mcp" \
  -H "Authorization: Bearer $MOONBOUNCE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | grep -o '"name":"evaluate"'

If it fails, email [e-mail] with the Request-Id response header of the failing call (add -i to see it).

Next

The Glossary collects every term from these guides, with a link to where each is explained.