# Ory MCP Server

An [MCP](https://modelcontextprotocol.io) server that exposes the [Ory CLI](https://www.ory.com/docs/guides/cli/installation) and the [Ory Network REST API](https://www.ory.com/docs/reference/api) as tools your AI agent can call: manage identities, OAuth2 clients, permission relationships, projects, configuration, and more directly from a chat session.

Every Ory agent plugin in this repo registers it for you, but it's a standalone MCP server; install it on its own and point any MCP-capable harness at it.

## How it works

The server speaks MCP over stdio and registers ~50 tools across two execution paths:

- **CLI-backed tools** shell out to the `ory` binary on your `PATH` (`--format json`). They cover identities, OAuth2 clients, relationships / permissions, projects, configuration, workspaces, organizations, JWKs, and event streams.
- **`ory_api_request`** calls the Ory Network REST API directly over HTTP. Use it for any endpoint the dedicated tools don't cover (self-service flows, sessions, recovery codes, consent challenges, schemas). The base URL comes from the `ory` CLI's selected project unless you pin one, so this tool needs no configuration of its own; an API key is only required for endpoints that demand an admin credential.

All logging goes to stderr; stdout is reserved for the MCP protocol.

## Prerequisites

- **Node.js ≥ 22.**
- **The `ory` CLI on `PATH`** for the CLI-backed tools. Install from [ory.com/docs/guides/cli/installation](https://www.ory.com/docs/guides/cli/installation), then authenticate with `ory auth`. (Set `ORY_CLI_PATH` if the binary lives elsewhere.)
- **Nothing extra** for the `ory_api_request` tool — it falls back to the CLI's selected project for the base URL. Set `ORY_PROJECT_URL` to pin one, and `ORY_API_KEY` only for admin endpoints.

## Install

```bash
npm install -g @ory/mcp-server
```

Then add it to your harness's MCP config. Most harnesses use the generic `mcpServers` shape; for example, Claude Code's `.claude/settings.json`:

```json
{ "mcpServers": { "ory": { "command": "ory-mcp-server" } } }
```

To always run the published version on demand instead of installing globally, point the command at `npx`:

```json
{
  "mcpServers": {
    "ory": {
      "command": "npx",
      "args": ["--package=@ory/mcp-server", "ory-mcp-server"]
    }
  }
}
```

> Config shapes vary by harness. OpenCode, for example, uses a `mcp` (singular) key with a `{ "type": "local", "command": [...] }` connector. Check your harness's MCP documentation for the exact schema; the `ory-mcp-server` binary (or the `npx` invocation above) is what every shape ultimately runs.

## Tools

- **Identities**: `list`, `get`, `delete`, `import`, `validate`.
- **OAuth2 / OIDC**: `list`, `get`, `create`, `update`, `import`, `delete` clients; `introspect`, `revoke`, `perform_client_credentials`; `delete_access_tokens`.
- **Relationships & Permissions**: `list`, `create`, `create_from_file`, `parse`, `delete`, `check_permission`.
- **Projects**: `list`, `get`, `create`, `update`, `patch`, `use`.
- **Configuration**: `get`, `update`, `patch` for identity / oauth2 / permission configs; `update_opl`, `patch_opl`.
- **Workspaces**: `list`, `get`, `create`.
- **Organizations (B2B)**: `list`, `create`, `update`, `delete`.
- **JWKs**: `create`, `get`, `delete`, `import`.
- **Event streams**: `list`, `create`, `update`, `delete`.
- **Generic REST**: `ory_api_request` for any Ory Network REST endpoint.

CLI-backed tools accept optional `project` and `workspace` parameters; defaults come from `ORY_PROJECT` / `ORY_WORKSPACE` or from whatever `ory use project` selected. Tools that take a file (imports, OPL, config updates) accept either a `file` path or inline `content`.

## Environment

| Variable | Default | Description |
|----------|---------|-------------|
| `ORY_CLI_PATH` | `ory` | Path to the `ory` CLI binary |
| `ORY_PROJECT` | _(none)_ | Default project ID/slug for CLI tools |
| `ORY_WORKSPACE` | _(none)_ | Default workspace ID/name for CLI tools |
| `ORY_CLI_TIMEOUT` | `30000` | CLI command timeout (ms) |
| `ORY_PROJECT_URL` | _the `ory` CLI's selected project_ | Base URL for `ory_api_request`. Unset, the tool asks the CLI which project is selected (`ory use project`) and derives `https://<slug>.projects.oryapis.com` from it. `ORY_PROJECT` pins which project is looked up. |
| `ORY_SDK_URL` | _(none)_ | Fallback base URL for `ory_api_request` when `ORY_PROJECT_URL` is unset |
| `ORY_API_KEY` | _(none)_ | Bearer token for `ory_api_request`. Only needed for endpoints requiring an admin credential — the CI/headless path, not the default. |
| `ORY_ACCESS_TOKEN` | _(none)_ | Fallback bearer for `ory_api_request` when `ORY_API_KEY` is unset |
| `ORY_HTTP_TIMEOUT` | `30000` | REST request timeout (ms) |
| `ORY_MCP_DEBUG` | `false` | Set to `true` for structured debug logging on stderr |

Per-call parameters on `ory_api_request` (`base_url`, `api_key`) override the corresponding env vars, and the env vars override the CLI fallback.

### Trusted hosts for `ory_api_request`

The env-configured credential (`ORY_API_KEY` / `ORY_ACCESS_TOKEN`) is only attached automatically when the request targets a trusted Ory origin: the origin of the configured `ORY_PROJECT_URL` / `ORY_SDK_URL`, an Ory Network host (`*.projects.oryapis.com` / `*.oryapis.com`) or `api.console.ory.sh` over https, or localhost (any port, for the local-dev stack). If a caller-supplied `base_url` points anywhere else, the request is still sent but without the env credential, and the tool result notes that it was withheld — this prevents a prompt-injected agent from exfiltrating your admin API key to an arbitrary host. An explicitly passed `api_key` parameter or `authorization` header is always honored as-is.

## Links

- [ory.com](https://ory.com)

## License

Apache-2.0