> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moonbounce.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your agent

> Use the API as MCP tools from a coding agent.

> [!NOTE]
>
> Access is by invitation: join the waitlist at [app.moonbounce.ai](https://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.

```bash theme={null}
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:

```bash theme={null}
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`:

```json theme={null}
{"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`:

```bash theme={null}
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](https://docs.moonbounce.ai/learn/engines-and-environments.md)). For Claude Code, put this in your repository's `.mcp.json` and start `claude` from a shell where `MOONBOUNCE_API_KEY` is exported:

```json .mcp.json theme={null}
{
  "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:

```bash theme={null}
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`:

```bash theme={null}
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:

```bash theme={null}
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](https://docs.moonbounce.ai/api-reference/evaluate/evaluate-an-item-against-a-decision.md) 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](https://docs.moonbounce.ai/learn/decisions.md), [Feedback](https://docs.moonbounce.ai/learn/feedback.md)).
* **Improve.** Ask for a suggestion with `generate_suggestion`, or list proposed ones with `list_suggestions`, and preview any change with `preview` ([Suggestions and previews](https://docs.moonbounce.ai/learn/improving.md)).
* **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

```bash theme={null}
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 [support@moonbounce.ai](mailto:support@moonbounce.ai?subject=Moonbounce%20API%20problem\&body=Request-Id%3A%20%0A%0AWhat%20happened%3A%0A) with the `Request-Id` response header of the failing call (add `-i` to see it).

## Next

The [Glossary](https://docs.moonbounce.ai/learn/glossary.md) collects every term from these guides, with a link to where each is explained.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.