# Oauth connections tools

> MCP tools for Oauth connections: oauth_connections_create, oauth_connections_list, oauth_connections_revoke.

- `oauth_connections_create`: Connect an MCP client to an organization (consent)
- `oauth_connections_list`: List your connected OAuth clients
- `oauth_connections_revoke`: Disconnect an OAuth client

## `oauth_connections_create`

**Connect an MCP client to an organization (consent).** Operation [`oauth_connections.create`](https://ownrecord.io/docs/reference/oauth-connections-create.md) · Platform level · permission `account:write` · risk tier `security` · since M10

Lets an OAuth client that acts for you, such as an MCP client, work in one of your organizations with the
scopes you consent to. The consent screen calls it when you approve the client's authorization request;
`grantId` is that request's grant. The client then acts as you, with at most your own role there (re-checked on
every call), and never decides approval requests. Connecting again to the same organization replaces its scopes.
Partner apps are installed with `app_installations.create` instead.

Annotations: `readOnlyHint: false` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type                                                                 | Required | Description                                                                                                                                                                                              |
| ----------------- | -------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientId`        | ID (`ocl_…`)                                                         | yes      | –                                                                                                                                                                                                        |
| `grantId`         | ID (`ogr_…`)                                                         | yes      | –                                                                                                                                                                                                        |
| `orgId`           | ID (`org_…`)                                                         | yes      | –                                                                                                                                                                                                        |
| `scopes`          | array of one of 84 values, e.g. `org:read`, `org:write`, `org:admin` | yes      | (1–200 items)                                                                                                                                                                                            |
| `idempotency_key` | string                                                               | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean                                                              | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed): A scope isn't one the client may receive, or the client is an app.
- [`oauth_client_disabled`](https://ownrecord.io/docs/reference/errors.md#oauth_client_disabled): The client is disabled.
- [`oauth_grant_mismatch`](https://ownrecord.io/docs/reference/errors.md#oauth_grant_mismatch): The grant isn't yours or isn't the client's.
- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): The client doesn't exist, or you aren't a member of the organization.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): This isn't a signed-in person in the console.

### Example

**Let Claude read filings and tasks**

Arguments:

```json
{
  "clientId": "ocl_01m4ttwd3veh9apbewxheq5xhe",
  "grantId": "ogr_01m4ttwd3veh9apbewxheq5xhd",
  "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
  "scopes": ["filings:read", "tasks:read"],
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "ogr_01m4ttwd3veh9apbewxheq5xhd",
  "object": "oauth_connection",
  "client": {
    "id": "ocl_01m4ttwd3veh9apbewxheq5xhe",
    "name": "Claude",
    "publisher": "Unverified (registered by the client itself)",
    "dynamic": true
  },
  "orgs": [
    {
      "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
      "scopes": ["filings:read", "tasks:read"],
      "consentedAt": "2026-10-25T09:00:00.000Z"
    }
  ],
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-25T09:00:00.000Z"
}
```

## `oauth_connections_list`

**List your connected OAuth clients.** Operation [`oauth_connections.list`](https://ownrecord.io/docs/reference/oauth-connections-list.md) · Platform level · permission `account:read` · risk tier `read` · since M10

Lists the OAuth clients (such as MCP clients) that act for you, with the organizations and scopes you connected them to, most recently changed first (at most 100). App installations aren't listed here: see `app_installations.list`.

Annotations: `readOnlyHint: true` · `destructiveHint: false` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

This tool takes no arguments.

- **Read-only:** changes nothing; `idempotency_key` is ignored.

### Errors

- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): This isn't a signed-in person in the console.

### Example

**Your connections**

Arguments:

```json
{}
```

Result `output`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "ogr_01m4ttwd3veh9apbewxheq5xhd",
      "object": "oauth_connection",
      "client": {
        "id": "ocl_01m4ttwd3veh9apbewxheq5xhe",
        "name": "Claude",
        "publisher": "Unverified (registered by the client itself)",
        "dynamic": true
      },
      "orgs": [
        {
          "orgId": "org_01m4ttwd3veh9apbewxheq5xh3",
          "scopes": ["filings:read", "tasks:read"],
          "consentedAt": "2026-10-25T09:00:00.000Z"
        }
      ],
      "createdAt": "2026-10-25T09:00:00.000Z",
      "updatedAt": "2026-10-25T09:00:00.000Z"
    }
  ]
}
```

## `oauth_connections_revoke`

**Disconnect an OAuth client.** Operation [`oauth_connections.revoke`](https://ownrecord.io/docs/reference/oauth-connections-revoke.md) · Platform level · permission `account:write` · risk tier `security` · since M10

Disconnects an OAuth client that acts for you from one organization (`orgId`), or from all of them. Its tokens
stop working there at once; once it covers no organization, every token and refresh token it holds is revoked.
Disconnecting it again changes nothing.

Annotations: `readOnlyHint: false` · `destructiveHint: true` · `idempotentHint: true` · `openWorldHint: false`

### Arguments

| Argument          | Type         | Required | Description                                                                                                                                                                                              |
| ----------------- | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`              | ID (`ogr_…`) | yes      | –                                                                                                                                                                                                        |
| `orgId`           | ID (`org_…`) | no       | –                                                                                                                                                                                                        |
| `idempotency_key` | string       | no       | A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters) |
| `dry_run`         | boolean      | no       | true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)                                                                                 |

- **Idempotency:** the result returns the `idempotency_key` used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
- **Dry run:** supported. `dry_run: true` checks permissions and rules and computes the result, then rolls everything back.

### Errors

- [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found): You have no connection with this ID.
- [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied): This isn't a signed-in person in the console.

### Example

**Disconnect from every organization**

Arguments:

```json
{
  "id": "ogr_01m4ttwd3veh9apbewxheq5xhd",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}
```

Result `output`:

```json
{
  "id": "ogr_01m4ttwd3veh9apbewxheq5xhd",
  "object": "oauth_connection",
  "client": {
    "id": "ocl_01m4ttwd3veh9apbewxheq5xhe",
    "name": "Claude",
    "publisher": "Unverified (registered by the client itself)",
    "dynamic": true
  },
  "orgs": [],
  "createdAt": "2026-10-25T09:00:00.000Z",
  "updatedAt": "2026-10-26T14:30:00.000Z"
}
```