Skip to main content

Model Context Protocol (MCP)

Zyphe ships a built-in Model Context Protocol server that lets AI agents and MCP-compatible clients (Claude Desktop, Claude Code, Cursor, and any other MCP host) manage your flows, forms, and API keys programmatically through natural language.

Instead of writing REST clients or learning the dashboard UI, you can simply ask your AI assistant "create a new KYC flow with a document verification step and a form". The agent will call the right MCP tools on your behalf.

info

The MCP server is exposed by the same Zyphe API server that handles REST traffic. There is no separate process or port to run.

Capabilities at a glance​

The MCP server exposes 36 tools in five groups. Thirteen of them work KYB cases and three dispose of AML screening hits, so an agent can carry a review from open case to approval or escalation, not only configure the flows that produce them.

  • KYB: read a KYB result, request and review business-information clarifications, correct field values, add or remove UBOs and directors, request per-country documents, send UBO KYC invitations, approve, or escalate to admin review.
  • AML: read a screening result, clear a false positive, or escalate to a human reviewer.
  • Flows: list, create, read, update, delete flows; manage flow-level settings (branding, webhooks).
  • Flow steps: add, update, and delete steps inside a flow (DV, FORM, POA, KYB, SPID, PHONE, WALLET, LIVENESS, AUTO_ONE_CLICK_KYC, DOCUMENT_SELECTION, GEOLOCATION).
  • Forms: list, create, read, update, delete forms with their sections.
  • API keys: list, create, read, update, delete API keys (SECRET and PUBLISHABLE).

The KYB and AML write tools are guarded server-side. approve_kyb_result refuses while any clarification is open or any document-backed field is not a match, and clear_aml_result refuses on a high-confidence sanctions match, Critical overall risk, a result already under a human verdict, or a screening with no identity discriminators. The guard is deterministic and lives on the server, so it holds whatever the calling model decides.

Every tools/call is recorded as a readable audit row carrying the tool name, redacted arguments, the mapped action, and the target resource id. Protocol traffic (initialize, tools/list, ping) is not logged.

Every tool accepts an optional sandbox: boolean flag so you can target the sandbox environment from the same connection.

Authentication​

The MCP server is authenticated with bot tokens. Bots are organization-scoped service identities; their permissions are evaluated by the same role-based access control policies that govern the REST API, so a bot can only do what its assigned role is allowed to do.

1. Create a bot and obtain a token​

Bot management lives under /organizations/{organization_id}/bots/... in the REST API:

Bots page with Create Bot button
Create and manage bot identities from the Bots page in the dashboard.
MethodPathPurpose
GET/organizations/{org_id}/bots/listList bots in the organization
POST/organizations/{org_id}/bots/createCreate a new bot (returns plain token)
GET/organizations/{org_id}/bots/{bot_id}/getFetch bot metadata
POST/organizations/{org_id}/bots/{bot_id}/regenerate-tokenIssue a new token; the previous one dies
DELETE/organizations/{org_id}/bots/{bot_id}/deleteSoft-delete the bot

The plain-text token is returned only once at creation (or regeneration). It looks like:

Create bot dialog
Create a bot to obtain a token that MCP-compatible clients can use.
zyphe_bot_<48 random alphanumeric characters>
Store the token securely

Tokens are SHA-256 hashed on the server, so Zyphe cannot retrieve a lost token. If you misplace one, regenerate it. Treat bot tokens like passwords: never commit them to source control, never paste them into chat logs.

2. Use the token​

Send it as a Bearer token on the Authorization header:

Authorization: Bearer zyphe_bot_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

If the header is missing or the token is invalid, the server responds with 401 Unauthorized. If the bot's role does not allow the requested operation, the tool call returns an MCP error with code INVALID_REQUEST and message "Permission denied".

Endpoint​

The MCP server is mounted on the same host and port as the Zyphe API:

POST {ZYPHE_API_BASE_URL}/mcp

It uses the Streamable HTTP transport from the MCP specification. Any MCP-compliant client that supports HTTP transport can connect to it.

Connecting a client​

Claude Desktop / Claude Code​

Add an entry to your mcp.json (or the equivalent config UI):

{
  "mcpServers": {
    "zyphe": {
      "transport": {
        "type": "http",
        "url": "https://api.zyphe.com/mcp",
        "headers": {
          "Authorization": "Bearer zyphe_bot_YOUR_TOKEN_HERE"
        }
      }
    }
  }
}

Replace https://api.zyphe.com with the URL of your Zyphe deployment, and substitute your bot token.

Cursor​

Cursor supports MCP via the same JSON config format. Add the snippet above to your Cursor MCP settings.

Generic / programmatic​

Any MCP client SDK (TypeScript, Python, etc.) that supports the streamable-HTTP transport can talk to /mcp. Point the transport at the URL and inject the Authorization header.

Tool reference​

All parameters use camelCase keys. Every tool also accepts an optional sandbox boolean (default false) to target the sandbox environment instead of production.

KYB​

Tools that work an existing KYB result. All of them take kybResultId, the UUID of the KYB result.

get_kyb_result​

Read-only. Get a KYB result by its ID, scoped to the bot's organization.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
sandboxbooleannoRead from the sandbox environment

get_pending_kyb_clarifications​

Read-only. List pending clarification requests for a KYB result. Required: kybResultId.

send_kyb_clarification_request​

Write. Request business-information clarification from the client. Moves the KYB next action to Client.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
documentNamestringyesClarification request title shown to the client
fieldsstring[]yesBusiness information field keys to clarify
descriptionstringnoClarification instructions for the client

review_kyb_clarification_field​

Write. Approve one submitted clarification field, but only when the cross-check classified it as an exact, auto-correct, or fuzzy match against the document-collected value. Does not approve the KYB.

Required: kybResultId, documentRequestId, fieldKey.

approve_kyb_result​

Write. Guarded final KYB approval. Approves only when no clarifications remain open and every document-backed business-information verification field is an exact, auto-correct, or fuzzy match.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
reasonstringnoAudit reason for the agent approval

mark_kyb_for_admin_review​

Write. Safely escalate a KYB result to human review. Does not approve the KYB. Required: kybResultId, reason.

send_ubo_kyc_reminder​

Write. Send the KYC invitation or reminder email to a single UBO, identified by its zero-based index in uboDefinitions. For an un-onboarded UBO this sends the initial invitation.

Required: kybResultId, recipientIndex (integer, minimum 0).

edit_kyb_business_information​

Write. Directly correct one or more business-information field values as a reviewer edit. Each edited field is marked as a verification match and any pending clarification on it is auto-resolved. Allowed only while the KYB result is under review.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
updatesobject[]yesEach { fieldKey, value }. Keys include companyName, registrationNumber, country, address, city, postZipCode, businessActivity, incorporationDate, companyType, contactEmail
reasonstringyesReason for the correction, recorded in the activity log

add_kyb_ubos​

Write. Add one or more UBOs to an existing KYB result. A UBO with an email is sent a KYC invitation and must complete full KYC; a UBO without an email is screened by name only (AML) and is not notified. Allowed only while the KYB is under review.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
personsobject[]yesEach requires firstName, lastName, dateOfBirth, country, gender; email optional

remove_kyb_ubo​

Write. Remove a UBO by its stable personId. Any name-only AML screening for that UBO is removed too. Allowed only while the KYB is under review.

add_kyb_directors​

Write. Add one or more directors. Same email and name-only semantics as add_kyb_ubos. Allowed only while the KYB is under review.

remove_kyb_director​

Write. Remove a director by its stable personId. Any name-only AML screening for that director is removed too.

request_kyb_document​

Write. Request a specific on-demand per-country document by its catalog key, validated against the KYB's country, and notify the client. Creates a Standard document request for the client to upload.

FieldTypeRequiredDescription
kybResultIdstringyesUUID of the KYB result
documentKeystringyesCatalog key of the on-demand document
descriptionstringnoInstructions shown to the client
recipientEmailstringnoRecipient override; defaults to the business contact email
subjectstringnoNotification email subject
bodystringnoNotification email body

AML​

get_aml_result​

Read-only. Get an AML screening result by its ID: the scored entity hits, submitted identity, adverse media, moderation state, and flags.

Required: amlResultId.

clear_aml_result​

Write. Guarded false-positive clear, moderating the screening to Approved. A deterministic server-side guard refuses to clear a high-confidence sanctions match, a Critical overall risk, a result already under a human verdict, or a screening lacking identity discriminators.

FieldTypeRequiredDescription
amlResultIdstringyesUUID of the AML result
reasonstringnoAudit reason for the clear

escalate_aml_result​

Write. Escalate a screening to a human reviewer, moderating it to Escalated. Use it for genuine or ambiguous hits, and state in the reason if enhanced due diligence is recommended.

Required: amlResultId, reason.

Flows​

list_flows​

List flows for the bot's organization, with optional pagination, sorting, and filtering.

FieldTypeRequiredDescription
skipintegernoRecords to skip (default 0)
takeintegernoRecords to return (default 100)
sortstringnoSort field and direction, e.g. "createdAt:desc"
filterstringnoSemicolon-separated triples "field:operator:value" (e.g. "flow_type:eq:KYC")
sandboxbooleannoUse sandbox environment

create_flow​

Create a new flow. Required: name, slug, successUrl.

FieldTypeDescription
namestringDisplay name of the flow
slugstringURL-safe identifier (e.g. "kyc-flow")
successUrlstringRedirect URL on successful completion
failureUrlstringRedirect URL on failure (optional)
sandboxbooleanCreate in sandbox environment

update_flow​

Update an existing flow's metadata. Required: flowId, name, slug, successUrl.

get_flow​

Get a flow by its ID. Required: flowId.

delete_flow​

Soft-delete a flow by its ID. Required: flowId.

get_flow_settings​

Get the settings (branding, webhook options) for a flow. Required: flowId.

update_flow_settings​

Update the settings for a flow. Required: flowId. All other fields are optional and patch-style; only provided fields are changed.

FieldTypeDescription
primaryColorstringPrimary brand color (hex)
secondaryColorstringSecondary brand color (hex)
profileImagestringURL of the organization logo
webhookSecretstringHMAC secret for webhook signature verification
extendedWebhookbooleanInclude extended data in webhook payloads
publishedbooleanWhether the flow is publicly accessible
skipSignedAccessbooleanSkip signed-URL access control

Flow steps​

create_flow_step​

Add a new step to a flow. Required: flowId, name, stepType, config, order.

FieldTypeDescription
flowIdstringUUID of the parent flow
namestringDisplay name of the step
stepTypestringOne of: DV, FORM, POA, KYB, SPID, PHONE, WALLET, LIVENESS, AUTO_ONE_CLICK_KYC, DOCUMENT_SELECTION, GEOLOCATION
configobjectStep configuration object (must contain a matching stepType discriminator)
orderintegerPosition of the step in the flow (0-based)
successUrlstringOverride success redirect URL for this step (optional)
failureUrlstringOverride failure redirect URL for this step (optional)
tip

Each step type has its own config schema. See the flow-step guides for the shape of each step's configuration.

update_flow_step​

Update a step's name, config, or redirect URLs. Required: flowId, stepId, config.

delete_flow_step​

Soft-delete a step from a flow. Required: flowId, stepId.

Forms​

list_forms​

List forms for the bot's organization, with optional pagination and sorting. Same pagination fields as list_flows (without filter).

create_form​

Create a new form. Required: name, sections.

FieldTypeDescription
namestringDisplay name of the form
sectionsarrayArray of FormSection objects

update_form​

Update a form's name and/or sections. Required: formId.

get_form​

Get a form by its ID. Required: formId.

delete_form​

Hard-delete a form by its ID. Required: formId.

API keys​

list_api_keys​

List API keys for the bot's organization.

create_api_key​

Create a new API key. Required: keyType. The plain-text key is returned once in the key field of the response, so store it immediately.

FieldTypeDescription
keyTypestringSECRET or PUBLISHABLE
namestringHuman-readable name (optional)
descriptionstringDescription (optional)
allowedOriginsarray of stringsAllowed CORS origins (optional)
optionsobjectAdditional options as a JSON object

get_api_key​

Get an API key by its ID. Required: apiKeyId.

update_api_key​

Update an API key's name, description, allowed origins, or options. Required: apiKeyId.

delete_api_key​

Soft-delete an API key by its ID. Required: apiKeyId.

Sandbox vs production​

Every tool takes an optional sandbox boolean. When true, the tool reads and writes against the sandbox dataset; when false or omitted, it operates on production data.

This means a single bot token can drive both environments, which is useful for agents that build a flow in sandbox, validate it, and then promote it to production in one session.

Error handling​

MCP errors follow the standard MCP error model:

ConditionError codeNotes
Missing or malformed parametersINVALID_PARAMSReturned when JSON parsing or schema check fails
Unknown tool nameMETHOD_NOT_FOUNDTool not registered on this server
RBAC policy denialINVALID_REQUESTMessage: "Permission denied"
Unexpected backend / DB / RBAC errorINTERNAL_ERRORServer-side failure; check Zyphe logs

HTTP-level failures (401, 403) are returned before the MCP envelope and indicate problems with the bot token or middleware, not with a specific tool call.

Example session​

A typical agent conversation with the Zyphe MCP server might look like this (paraphrased; the agent translates intent into tool calls):

You: Create a sandbox flow called "Onboarding Test" with a document verification step.

Agent:

  1. calls create_flow with { name: "Onboarding Test", slug: "onboarding-test", successUrl: "...", sandbox: true }
  2. takes the returned flowId and calls create_flow_step with { flowId, name: "DV", stepType: "DV", config: { stepType: "DV", ... }, order: 0, sandbox: true }
  3. returns: "Created sandbox flow onboarding-test (id …) with one DV step at position 0."

A case-work session looks different, because the agent is disposing of real compliance work rather than configuring it:

You: Take a look at AML result … and clear it if it is obviously a false positive.

Agent:

  1. calls get_aml_result with { amlResultId: "…" } and reads the scored hits, submitted identity, and adverse media
  2. decides the hit is a common-name collision with no matching date of birth or nationality
  3. calls clear_aml_result with { amlResultId: "…", reason: "Name-only collision; DOB and nationality both mismatch the listed entity." }
  4. returns: "Cleared. Had the guard refused — high-confidence sanctions match, Critical risk, existing human verdict, or no identity discriminators — I would have escalated instead."

The agent's judgement is not what makes this safe. The server-side guard is: if the screening had been a high-confidence sanctions match, clear_aml_result would have refused the call regardless of what the model concluded, and the correct next step would have been escalate_aml_result.

Security notes​

  • The KYB and AML write tools carry deterministic server-side guards. approve_kyb_result and clear_aml_result refuse unsafe calls on the server, so the guarantee does not depend on the calling model's reasoning or on prompt wording.
  • Bot tokens authenticate at the request level; the MCP transport does not add a separate session layer.
  • All tool calls are subject to the same role-based access control policies that govern the REST API. A bot scoped to a specific role cannot escalate privileges through MCP.
  • Token hashes are stored with SHA-256; plain-text tokens are never persisted.
  • Regenerating a bot's token instantly invalidates the previous one. Use this if you suspect leakage.