# MCP server

> Connect Claude, Cursor, VS Code or any MCP client to OKYC — create sessions, review cases, build workflows and read the docs from your AI assistant.

Source: https://docs.okyc.stream/ai/mcp

OKYC runs a hosted [Model Context Protocol](https://modelcontextprotocol.io) server. Once connected, your AI
assistant can set up an integration end to end (workflow, test session, webhook), look up and review sessions,
and answer questions from these docs.

|                     |                                                                    |
| ------------------- | ------------------------------------------------------------------ |
| URL                 | `https://mcp.okyc.stream/mcp`                                      |
| Transport           | Streamable HTTP (stateless)                                        |
| Sign-in             | OAuth 2.1 with PKCE — you sign in with your OKYC dashboard account |
| Client registration | Client ID Metadata Documents, or dynamic client registration       |
| Scopes              | `okyc:read` (look things up), `okyc:write` (create and change)     |

## Connect

The first time you use it, your client opens the OKYC dashboard: sign in (with 2FA if you use it) and approve
access. The client then acts **as you, with your role**, in the organizations you belong to. Tools take optional
`organization_id` and `project_id`: you only need them when you belong to several organizations or an
organization has several [projects](https://docs.okyc.stream/concepts/projects.md) — `list_organizations` lists both. A test key already
names its project.

**Claude Code**

```bash title="claude-code.sh"
claude mcp add --transport http okyc https://mcp.okyc.stream/mcp
```

**Claude (web and desktop):** Settings → Connectors → Add custom connector, name `OKYC`, URL
`https://mcp.okyc.stream/mcp`.

**Cursor**

```json title="cursor.mcp.jsonc"
{
  "mcpServers": {
    "okyc": { "url": "https://mcp.okyc.stream/mcp" }
  }
}
```

**VS Code**

```json title="vscode.mcp.jsonc"
{
  "servers": {
    "okyc": { "type": "http", "url": "https://mcp.okyc.stream/mcp" }
  }
}
```

**Headless (CI, scripts):** instead of signing in, send a **test** secret key. Live keys are refused — they
must never sit in an AI tool's configuration.

```json title="headless.mcp.jsonc"
{
  "mcpServers": {
    "okyc-sandbox": {
      "url": "https://mcp.okyc.stream/mcp",
      "headers": { "Authorization": "Bearer ${OKYC_TEST_KEY}" }
    }
  }
}
```

The dashboard's **Developers → AI tools (MCP)** page shows the same setup, and lists connected tools so you can
disconnect them.

## Safety

* **Test mode by default.** Every tool takes `mode`; it is `test` unless you (or your assistant, because you
  asked) pass `live`. Some tools are test-only: running checks directly, trying a draft, creating API keys.
* **Your role applies.** Tools go through the same API as the dashboard: a reviewer cannot publish workflows,
  a developer cannot decide sessions, audit events are admin-only.
* **Personal data stays out of AI context.** Tool results are sent to your AI provider. In live mode, names,
  dates of birth, addresses, document numbers and extracted fields are masked unless an admin turns on
  *Share personal data with AI tools* (Developers → AI tools). Evidence files are never available.
* **Not available from AI tools:** erasing personal data, creating live API keys, overriding a final decision,
  and changing settings. Use the dashboard.
* **Approval before changes.** Tools are annotated read-only, write or destructive; MCP clients ask you before
  running write and destructive tools — keep that on.
* **Audited.** Every call is recorded in the audit log as you, via the MCP client (`mcp.tool_called`), in
  addition to what the underlying action records.
* **Rate limit:** 120 tool calls per minute per person or key.

## Prompts and resources

* Prompt **Integrate OKYC into my app** — plans and implements an integration for your stack, in test mode.
* Prompt **Review a session** — explains why a session needs review and recommends a decision (without deciding).
* Resource `okyc://docs/llms.txt` — the documentation index (same as [https://docs.okyc.stream/llms.txt](https://docs.okyc.stream/llms.txt)).

## Tools

| Tool                      | Kind        | Modes      | What it does                                                                                                                                                                      |
| ------------------------- | ----------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_organizations`      | read-only   | —          | Organizations you belong to, with your role and each organization’s projects. Pass `organization_id` / `project_id` to other tools when there is more than one.                   |
| `get_usage`               | read-only   | test, live | Checks and sessions used in the last 90 days, by check and provider.                                                                                                              |
| `list_audit_events`       | read-only   | test, live | Recent audit log (who did what, never values). Admins and owners only.                                                                                                            |
| `list_api_keys`           | read-only   | test, live | API keys of this mode: name, prefix, last use. Secrets are never returned.                                                                                                        |
| `create_test_api_key`     | write       | test only  | Create a sandbox secret key (sk\_test\_…) for a backend integration. Returned once. Live keys can only be created in the dashboard.                                               |
| `create_session`          | write       | test, live | Create a session for one applicant and get its `url` (open it in a browser or pass it to an SDK). Test mode by default.                                                           |
| `list_sessions`           | read-only   | test, live | Most recent sessions, newest first. Filter by status (e.g. review, approved), type or workflow.                                                                                   |
| `get_session`             | read-only   | test, live | Everything about one session: steps, checks (with `verified_by`), decisions and rules fired, screening hits, manual checks waiting for review, timeline.                          |
| `get_review_queue`        | read-only   | test, live | Sessions waiting for a reviewer, oldest first, with the reasons they need review.                                                                                                 |
| `get_evaluation_preview`  | read-only   | test, live | What the rules would decide now with current data (after corrections or manual reviews). Records nothing.                                                                         |
| `review_manual_check`     | write       | test, live | For checks verified by a reviewer (provider `manual`): confirm or reject against the uploaded document. Only before a final decision. Find them in get\_session → manual\_checks. |
| `decide_session`          | destructive | test, live | Approve, decline or request resubmission of a session waiting in `review`. Final decisions cannot be overridden from an AI tool (use the dashboard).                              |
| `cancel_session`          | destructive | test, live | Cancel an active session; its link stops working.                                                                                                                                 |
| `list_workflow_templates` | read-only   | test, live | Ready-made workflow definitions (e.g. India KYC standard) to start from.                                                                                                          |
| `list_workflows`          | read-only   | test, live | Workflows of the organization with their current version.                                                                                                                         |
| `get_workflow`            | read-only   | test, live | A workflow with its current definition and version history.                                                                                                                       |
| `get_verification_setup`  | read-only   | test, live | Which steps are verified manually by a reviewer (no registry connected) and which integrations (DigiLocker, phone OTP) are configured for live mode.                              |
| `validate_workflow`       | read-only   | test, live | Report every issue (errors and warnings, per step) in a definition without saving it.                                                                                             |
| `list_rule_fields`        | read-only   | test, live | Variables rules can use for a definition (check statuses, scores, name/DOB matches…).                                                                                             |
| `create_workflow`         | write       | test, live | Create and publish a new workflow (version 1). Validate it first with validate\_workflow.                                                                                         |
| `save_workflow_draft`     | write       | test, live | Save an unpublished draft (shared with the dashboard builder). Returns its validation.                                                                                            |
| `test_workflow_draft`     | write       | test only  | Create a sandbox session running a draft definition, without publishing it. Test mode only.                                                                                       |
| `publish_workflow`        | write       | test, live | Publish a new version; new sessions use it (running sessions keep theirs).                                                                                                        |
| `run_check`               | write       | test only  | Run one check without a session, e.g. in.pan.verify with sandbox magic values. Test mode only (live checks may cost money and must come from your backend).                       |
| `list_capabilities`       | read-only   | test, live | Workflow step capabilities per country and the checks they run.                                                                                                                   |
| `list_document_types`     | read-only   | test, live | Documents the documents step can request, with every extractable field fully described.                                                                                           |
| `list_webhook_endpoints`  | read-only   | test, live | Webhook endpoints of this mode and the events they receive.                                                                                                                       |
| `create_webhook_endpoint` | write       | test, live | Register an HTTPS endpoint for events (e.g. session.approved). Returns its signing secret once.                                                                                   |
| `delete_webhook_endpoint` | destructive | test, live | Stop sending events to an endpoint.                                                                                                                                               |
| `list_webhook_deliveries` | read-only   | test, live | Recent delivery attempts for an endpoint (status, response code, retries).                                                                                                        |
| `search_docs`             | read-only   | —          | Find documentation pages (integration guides, SDKs, API, concepts) for a question.                                                                                                |
| `get_doc_page`            | read-only   | —          | A documentation page as Markdown, e.g. /mobile/android or /backend/webhooks.                                                                                                      |

### list\_organizations

List organizations. Organizations you belong to, with your role and each organization’s projects. Pass `organization_id` / `project_id` to other tools when there is more than one.

No arguments.

### get\_usage

Get usage. Checks and sessions used in the last 90 days, by check and provider.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### list\_audit\_events

List audit events. Recent audit log (who did what, never values). Admins and owners only.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### list\_api\_keys

List API keys. API keys of this mode: name, prefix, last use. Secrets are never returned.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### create\_test\_api\_key

Create a test API key. Create a sandbox secret key (sk\_test\_…) for a backend integration. Returned once. Live keys can only be created in the dashboard.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument | Type   | Required | Description                   |
| -------- | ------ | -------- | ----------------------------- |
| `name`   | string | yes      | Label, e.g. "staging backend" |

### create\_session

Create a verification session. Create a session for one applicant and get its `url` (open it in a browser or pass it to an SDK). Test mode by default.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument       | Type    | Required | Description |
| -------------- | ------- | -------- | ----------- |
| `workflow_id`  | string  | yes      | —           |
| `reference_id` | string  |          | —           |
| `country`      | string  |          | —           |
| `prefill`      | object  |          | —           |
| `locale`       | string  |          | —           |
| `redirect_url` | string  |          | —           |
| `metadata`     | object  |          | —           |
| `expires_in`   | integer |          | —           |

### list\_sessions

List sessions. Most recent sessions, newest first. Filter by status (e.g. review, approved), type or workflow.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type           | Required | Description                                                      |
| ------------- | -------------- | -------- | ---------------------------------------------------------------- |
| `status`      | string         |          | created, in\_progress, processing, review, approved, declined, … |
| `type`        | "kyc" \| "kyb" |          | —                                                                |
| `workflow_id` | string         |          | —                                                                |
| `q`           | string         |          | Search: reference id or session id                               |
| `limit`       | integer        |          | —                                                                |

### get\_session

Get a session. Everything about one session: steps, checks (with `verified_by`), decisions and rules fired, screening hits, manual checks waiting for review, timeline.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `session_id` | string | yes      | Session id  |

### get\_review\_queue

Get the review queue. Sessions waiting for a reviewer, oldest first, with the reasons they need review.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### get\_evaluation\_preview

Preview the automatic decision. What the rules would decide now with current data (after corrections or manual reviews). Records nothing.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `session_id` | string | yes      | Session id  |

### review\_manual\_check

Confirm or reject a manual check. For checks verified by a reviewer (provider `manual`): confirm or reject against the uploaded document. Only before a final decision. Find them in get\_session → manual\_checks.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type                                                                                                   | Required | Description             |
| ------------ | ------------------------------------------------------------------------------------------------------ | -------- | ----------------------- |
| `session_id` | string                                                                                                 | yes      | Session id              |
| `check_id`   | string                                                                                                 | yes      | Check id                |
| `decision`   | "confirmed" \| "rejected"                                                                              | yes      | —                       |
| `reason`     | "document\_mismatch" \| "document\_unreadable" \| "document\_invalid" \| "suspected\_fraud" \| "other" |          | Required when rejecting |
| `note`       | string                                                                                                 |          | —                       |

### decide\_session

Decide a session in review. Approve, decline or request resubmission of a session waiting in `review`. Final decisions cannot be overridden from an AI tool (use the dashboard).

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type                                                  | Required | Description                                               |
| ------------- | ----------------------------------------------------- | -------- | --------------------------------------------------------- |
| `session_id`  | string                                                | yes      | Session id                                                |
| `outcome`     | "approved" \| "declined" \| "resubmission\_requested" | yes      | —                                                         |
| `reason_code` | string                                                | yes      | e.g. manual\_verified, fraud\_suspected, blurry\_document |
| `note`        | string                                                |          | —                                                         |
| `steps`       | string\[]                                             |          | Steps to redo (resubmission\_requested only)              |

### cancel\_session

Cancel a session. Cancel an active session; its link stops working.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description |
| ------------ | ------ | -------- | ----------- |
| `session_id` | string | yes      | Session id  |

### list\_workflow\_templates

List workflow templates. Ready-made workflow definitions (e.g. India KYC standard) to start from.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### list\_workflows

List workflows. Workflows of the organization with their current version.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### get\_workflow

Get a workflow. A workflow with its current definition and version history.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description |
| ------------- | ------ | -------- | ----------- |
| `workflow_id` | string | yes      | Workflow id |

### get\_verification\_setup

Get verification setup. Which steps are verified manually by a reviewer (no registry connected) and which integrations (DigiLocker, phone OTP) are configured for live mode.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument  | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `country` | string |          | —           |

### validate\_workflow

Validate a workflow definition. Report every issue (errors and warnings, per step) in a definition without saving it.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `definition` | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |

### list\_rule\_fields

List rule fields. Variables rules can use for a definition (check statuses, scores, name/DOB matches…).

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `definition` | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |

### create\_workflow

Create a workflow. Create and publish a new workflow (version 1). Validate it first with validate\_workflow.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument     | Type   | Required | Description                                                                                       |
| ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `name`       | string | yes      | —                                                                                                 |
| `definition` | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |

### save\_workflow\_draft

Save a workflow draft. Save an unpublished draft (shared with the dashboard builder). Returns its validation.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description                                                                                       |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `workflow_id` | string | yes      | Workflow id                                                                                       |
| `definition`  | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |
| `name`        | string |          | —                                                                                                 |

### test\_workflow\_draft

Try a draft in a test session. Create a sandbox session running a draft definition, without publishing it. Test mode only.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description                                                                                       |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `workflow_id` | string | yes      | Workflow id                                                                                       |
| `definition`  | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |

### publish\_workflow

Publish a workflow version. Publish a new version; new sessions use it (running sessions keep theirs).

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description                                                                                       |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `workflow_id` | string | yes      | Workflow id                                                                                       |
| `definition`  | object | yes      | Workflow definition (type, country, steps, rules, default\_outcome, settings) — see get\_workflow |
| `name`        | string |          | —                                                                                                 |

### run\_check

Run a check (sandbox). Run one check without a session, e.g. in.pan.verify with sandbox magic values. Test mode only (live checks may cost money and must come from your backend).

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument    | Type   | Required | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `check_key` | string | yes      | e.g. in.pan.verify, tax\_id.verify |
| `input`     | object | yes      | —                                  |

### list\_capabilities

List capabilities. Workflow step capabilities per country and the checks they run.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### list\_document\_types

List document types. Documents the documents step can request, with every extractable field fully described.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument  | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `country` | string |          | —           |

### list\_webhook\_endpoints

List webhook endpoints. Webhook endpoints of this mode and the events they receive.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

No arguments.

### create\_webhook\_endpoint

Create a webhook endpoint. Register an HTTPS endpoint for events (e.g. session.approved). Returns its signing secret once.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument | Type      | Required | Description                                                       |
| -------- | --------- | -------- | ----------------------------------------------------------------- |
| `url`    | string    | yes      | —                                                                 |
| `events` | string\[] |          | Event types or patterns, default \["*"], e.g. \["session.*"] |

### delete\_webhook\_endpoint

Delete a webhook endpoint. Stop sending events to an endpoint.

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| `endpoint_id` | string | yes      | Webhook endpoint id |

### list\_webhook\_deliveries

List webhook deliveries. Recent delivery attempts for an endpoint (status, response code, retries).

Also takes `organization_id` (optional when you belong to one organization) and `mode` (`test` by default).

| Argument      | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| `endpoint_id` | string | yes      | Webhook endpoint id |

### search\_docs

Search the OKYC docs. Find documentation pages (integration guides, SDKs, API, concepts) for a question.

| Argument | Type   | Required | Description |
| -------- | ------ | -------- | ----------- |
| `query`  | string | yes      | —           |

### get\_doc\_page

Read a docs page. A documentation page as Markdown, e.g. /mobile/android or /backend/webhooks.

| Argument | Type   | Required | Description                 |
| -------- | ------ | -------- | --------------------------- |
| `path`   | string | yes      | Page path from search\_docs |