# Account MCP connector

Read governance state through OAuth or the local read-only server.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/mcp/account

## Remote account access

Add `https://api.kastra.ai/mcp/account` as a custom MCP connector in a client that supports the OAuth flow. Complete browser authorization for the intended workspace and environment scope. The account-read scope is `kastra.account.read`.

This is separate from the public onboarding endpoint and the remote gateway proxy. An account-read grant does not authorize third-party tools.

## Local inspection server

After an Edge login:

```sh
kastra-edge install-mcp
```

This registers `kastra-mcp` under the host server name `kastra-edge` for Claude Code. Use `kastra-edge install-mcp --target cursor` or `kastra-edge install-mcp --target codex` for those clients. Preview with `--dry-run`, then restart the selected client and verify that it can read the intended workspace. Configuration is separate from a successful connection or hook enforcement.

## Available read-only tools

All arguments are optional unless marked required. These tools read governance state; they do not change policy or approve actions.

| Tool | Arguments |
| --- | --- |
| `search_decisions` | `environment` (name), `decision` (`ALLOW`, `DENY`, `PENDING_REVIEW`), `from` / `to` (RFC3339), `source`, `actor_email` (case-insensitive substring), `limit` (default 50, maximum 200) |
| `get_active_policy` | `environment` (name; otherwise the connection's configured scope) |
| `list_incidents` | `environment`, `include_resolved` (boolean, default false) |
| `list_environments` | None |
| `list_policies` | None; authorized workspace/scope |
| `list_policy_revisions` | **Required:** `policy_id` (UUID from `list_policies`) |
| `get_rule_stats` | `environment` (name; defaults to configured scope) |
| `get_activity_stats` | `include_trends` (boolean, default false); `bucket` (`hour`, `day`, `week`, `month`, default `day`); `since` (window such as `24h`, `7d`, `30d`, default `30d`) |
| `verify_audit_chain` | None |
| `list_audit_events` | `limit` (default 50) |
| `list_api_keys` | None; masked key metadata only |
| `list_checkpoints` | `status`: `pending`, `approved`, `denied`, `expired`, `abandoned`, or `cancelled` |
| `get_governance_preferences` | None |

`search_decisions.source` accepts `server`, `claude_code`, `codex_cli`, `mcp`, `desktop_agent`, `browser_ext`, `manual`, `openclaw`, `cursor`, `proxy`, `sdk`, or `hermes`. These are recorded source identifiers, not a list of separately installable products.

Environment arguments use names, not UUIDs. An environment-scoped OAuth connection remains limited to its authorized scope even when a tool has no environment argument. For checkpoints, read `effective_decision`; terminal status alone is not permission. Local-only diagnostic tools are separate from this shared set.

## Example tool calls

A host sends these as the `params` of MCP `tools/call`. Replace `dev` with an authorized environment name.

```json
{
  "name": "search_decisions",
  "arguments": {
    "environment": "dev",
    "decision": "DENY",
    "source": "claude_code",
    "limit": 10
  }
}
```

```json
{
  "name": "get_activity_stats",
  "arguments": {
    "include_trends": true,
    "bucket": "day",
    "since": "7d"
  }
}
```

For a policy review, call `list_policies` with `{}`, take the actual returned policy ID, then call `list_policy_revisions` with `{"policy_id":"RETURNED_POLICY_UUID"}`. Handle MCP tool errors explicitly; an empty result or unavailable server is not evidence that no policy applies.

## Verify and disconnect

Ask for the active policy in a known environment and compare it with the console. Verify a sample decision by ID rather than assuming similarly named workspaces are the same. Revoke the connector grant when access is no longer needed. Read-only inspection does not install a blocking hook; follow an [Edge integration guide](https://docs.kastra.ai/edge/install) for enforcement.