Bynn MCP

https://mcp.bynn.com

The endpoint is the root path. Do not append /mcp; https://mcp.bynn.com/mcp will
not work. The only other route is GET /health.

Quick start (30 seconds)

Claude Code:

claude mcp add --transport http bynn https://mcp.bynn.com

Claude or ChatGPT (hosted): add https://mcp.bynn.com as a custom connector and sign in
with your Bynn account when the browser opens. No key handling needed.

API-style clients: get a token at dashboard.bynn.com/authenticate
and send it as Authorization: Bearer <token> on the connection.

Then try your first prompt:

Check whether this image is AI-generated.

Attach an image, and the result renders as an interactive card with the verdict, AI
probability, and most likely generator.

Example prompts

Fraud and documents

Submit this bank statement for fraud analysis and summarize the risk when it finishes.
Is this invoice manipulated? Show me the forensic findings.
Run my passport-fraud orchestrator against the latest analyzed document.

Verification

Create a KYC verification session for this applicant and give me the hosted link.
Estimate the age of the person in this photo and tell me if they look under 25.
Create an age verification session with liveness for user 8841.

Moderation and media

Check whether this image is AI-generated.
Which moderation models can I run on video?
Search this face against my employees collection.

Account and operations

List my API keys and when they were last used.
Rotate my live private key but keep the grace period.
Show this month's usage and my latest invoices.

Document-fraud and AI-image results render as interactive cards in both ChatGPT and Claude
(see Interactive widgets).

Installation

Claude Code

claude mcp add --transport http bynn https://mcp.bynn.com

Claude Desktop and claude.ai

Settings → Connectors → Add custom connector → URL https://mcp.bynn.com.
OAuth sign-in starts automatically on first use.

ChatGPT

Settings → Apps & Connectors → enable developer mode → Create → MCP server URL
https://mcp.bynn.com. Bynn is built as a ChatGPT app: fraud reports and AI-image checks
render as interactive cards, and attached images are forwarded to the tools natively.

Cursor

One click above, or add manually to ~/.cursor/mcp.json (or .cursor/mcp.json per project):

{
  "mcpServers": {
    "bynn": {
      "url": "https://mcp.bynn.com"
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json:

{
  "servers": {
    "bynn": {
      "type": "http",
      "url": "https://mcp.bynn.com"
    }
  }
}

Windsurf

Windsurf connects through the mcp-remote bridge:

{
  "mcpServers": {
    "bynn": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.bynn.com"]
    }
  }
}

Zed

settings.json → context_servers:

{
  "context_servers": {
    "bynn": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-remote", "https://mcp.bynn.com"]
      }
    }
  }
}

Authentication

OAuth 2.1 (connectors)

Hosted connectors (Claude, ChatGPT) authenticate with OAuth 2.1 + PKCE. The authorization
server is dashboard.bynn.com; your MCP client opens a browser sign-in, you approve the
requested permissions, and the client connects as your Bynn dashboard user. Clients that
support Dynamic Client Registration (Claude, Cursor) register automatically.

Bearer tokens (API-style clients)

For server-side, scripted, or self-hosted use, send an authorization header on the MCP
connection:

Authorization: Bearer <token>

Get a token at dashboard.bynn.com/authenticate.
Three token types work:

Token	Prefix	What it can do
Dashboard token (JWT)	none	Everything. When a tool needs an API key, the server exchanges the JWT for your organization's keys automatically.
Private API key	`private_...`	Product and verification tools (documents, moderation, age results). Not sufficient for dashboard tools like API keys or billing.
Public API key	`public_...`	Client-safe session creation (`create_session`, `create_age_verification_session`).

Per tool group:

Tool group	Minimum credential
API keys, billing, users, AutoDoc, reasoning, websites	Dashboard token (JWT)
Documents, moderation, face, NFC	Private key or JWT
`create_session`, `create_age_verification_session`	Public key or JWT
`verify_age_from_selfie`, `get_age_verification_result`	Private key or JWT
Session steps (consent, preflight, liveness, uploads)	None: the session token in the URL is the credential

Use private keys only in trusted server-side environments. Never expose them in frontend
code, public repositories, or shared chats.

Example client configuration with a token

{
  "mcpServers": {
    "bynn": {
      "url": "https://mcp.bynn.com",
      "headers": {
        "Authorization": "Bearer ${BYNN_API_KEY}"
      }
    }
  }
}

export BYNN_API_KEY="private_your_bynn_key_here"

Tools reference (143 tools)

Access badges: Read = safe, non-mutating. Write = creates or changes data.
Destructive = deletes, cancels, or revokes (delete_*, cancel_*, rotate_api_key);
keep confirmation enabled for these in your client. Every tool also carries machine-readable
readOnlyHint / destructiveHint annotations, so MCP clients can gate them automatically.

Documents (4)

Tool	Access	Description
`delete_document`	Destructive	Delete a document submission.
`get_document`	Read	Retrieve a document submission and its forensic analysis result.
`list_documents`	Read	List and search your document submissions.
`submit_document`	Write	Submit a document for full fraud / authenticity analysis.

Document analysis is asynchronous: submit_document, then poll get_document until
status is analyzed.

Age Verification (5)

Tool	Access	Description
`complete_age_verification_liveness`	Write	Finalize a liveness capture.
`create_age_verification_session`	Write	Create a new liveness age-verification session.
`get_age_verification_result`	Read	Read the result of a liveness age-verification session.
`start_age_verification_liveness`	Write	Start the liveness capture for a session.
`verify_age_from_selfie`	Write	Estimate age from a single selfie, without liveness.

verify_age_from_selfie takes an age_verification_model threshold (21, 18, and lower,
default 18) plus a legal_age_21 jurisdiction flag. The liveness flow is:
create session → start liveness → complete liveness → get result.

Content Moderation (12)

Tool	Access	Description
`check_age`	Write	Estimate the age of faces in an image (age verification / minor detection).
`create_moderation_inference`	Write	Run a moderation / AI-detection inference.
`detect_ai_generated_image`	Write	Check whether an image is AI-generated or a real photo.
`get_moderation_dashboard_stats`	Read	Get moderation dashboard statistics for your organization.
`get_moderation_inference`	Read	Retrieve a past moderation inference by its id.
`get_moderation_model`	Read	Get one moderation model with full documentation.
`list_all_moderation_models`	Read	List ALL public moderation models across every type.
`list_audio_moderation_models`	Read	List AUDIO moderation models grouped by category.
`list_image_moderation_models`	Read	List IMAGE moderation models grouped by category.
`list_text_moderation_models`	Read	List TEXT moderation models grouped by category.
`list_video_moderation_models`	Read	List VIDEO moderation models grouped by category.
`public_moderation_inference`	Write	Run a FREE public AI-detection inference, no credential required.

detect_ai_generated_image returns result.is_ai_generated (the verdict),
ai_probability, uncertain, top_generator, generators, c2pa_signer, and
detection_mode. check_age returns per-face age, from_age/to_age, is_minor,
challenge_25, sex, confidence, uncertainty, and bbox.

Face Search (6)

Tool	Access	Description
`create_face_collection`	Write	Create a new face collection.
`delete_face`	Destructive	Delete a single enrolled face from a collection.
`delete_face_collection`	Destructive	Delete a face collection and ALL its enrolled faces.
`enroll_face`	Write	Enroll a single face into a collection.
`list_face_collections`	Read	List your organization's face collections.
`search_faces`	Read	Search a collection for faces similar to a probe image.

AutoDoc (37)

Tool	Access	Description
`add_dossier_note`	Write	Add an admin note to a dossier.
`approve_approval`	Write	Approve a pending HITL approval.
`attach_dossier_tag`	Write	Attach an organization tag to a dossier.
`create_document_collection`	Write	Create a document collection.
`create_invitation`	Write	Send an AutoDoc invitation by email or SMS.
`create_organization_tag`	Write	Create an organization tag.
`create_workflow`	Write	Create a workflow.
`delete_document_collection`	Destructive	Delete a document collection (soft delete).
`delete_invitation`	Destructive	Cancel (hard-delete) a pending AutoDoc invitation.
`delete_organization_tag`	Destructive	Delete an organization tag.
`delete_workflow`	Destructive	Delete a workflow (soft delete).
`detach_dossier_tag`	Write	Detach an organization tag from a dossier.
`download_dossier_zip`	Read	Package a dossier's documents + variables into a ZIP.
`duplicate_workflow`	Write	Duplicate a workflow.
`get_autodoc_dashboard_stats`	Read	Get aggregated AutoDoc dashboard statistics.
`get_document_collection`	Read	Get one document collection and its requirements.
`get_dossier`	Read	Get one dossier with progress and workflow variables.
`get_dossier_form_fields`	Read	List form-field names available across your active workflows.
`get_invitation`	Read	Get a single AutoDoc invitation.
`get_pending_approval_count`	Read	Get the count of pending HITL approvals.
`get_workflow`	Read	Get a single workflow.
`list_approvals`	Read	List human-in-the-loop workflow approvals.
`list_document_collections`	Read	List document collections for your organization.
`list_document_types`	Read	List the document types available for collection requirements.
`list_dossier_documents`	Read	List the documents uploaded to a dossier.
`list_dossier_notes`	Read	List a dossier's notes / audit timeline.
`list_dossiers`	Read	List and filter AutoDoc dossiers.
`list_invitation_locales`	Read	List supported invitation locales.
`list_invitations`	Read	List AutoDoc invitations.
`list_organization_tags`	Read	List your organization's dossier tags.
`list_workflows`	Read	List workflows for your organization.
`reject_approval`	Write	Reject a pending HITL approval.
`resend_invitation`	Write	Resend an AutoDoc invitation.
`update_document_collection`	Write	Update a document collection and (optionally) its requirements.
`update_dossier`	Write	Rename a dossier.
`update_organization_tag`	Write	Update an organization tag's color and/or name.
`update_workflow`	Write	Update a workflow.

Reasoning & Fraud Agents (25)

Tool	Access	Description
`create_fraud_agent`	Write	Create a fraud-analysis agent / operator.
`create_orchestrator`	Write	Create an orchestrator (coordinator) agent.
`create_reasoning_job`	Write	Queue an ASYNCHRONOUS fraud-reasoning job for a document.
`delete_fraud_agent`	Destructive	Delete a fraud-analysis agent / operator.
`delete_orchestrator`	Destructive	Delete an orchestrator agent.
`generate_fraud_agent_prompt`	Write	Draft a fraud-analysis agent system prompt with AI.
`generate_orchestrator_prompt`	Write	Draft an orchestrator system prompt with AI.
`get_agent`	Read	Get a single agent (orchestrator or operator) by token.
`get_agent_stats`	Read	Get aggregate agent statistics for your organization.
`get_reasoning_job`	Read	Get a reasoning job's status and full results.
`list_agent_categories`	Read	List the available agent category options.
`list_agent_ratings`	Read	List ratings and rating summary for a public agent.
`list_document_content_types`	Read	List document content types and which are already claimed.
`list_fraud_agents`	Read	List YOUR organization's fraud-analysis agents / operators.
`list_orchestrators`	Read	List YOUR organization's orchestrator agents.
`list_public_fraud_agents`	Read	Browse public fraud-analysis agent templates from the global community.
`list_public_orchestrators`	Read	Browse public orchestrator templates from the global community.
`list_reasoning_jobs`	Read	List reasoning jobs with filters and org-wide stats.
`publish_agent`	Write	Publish one of your agents to the public community marketplace.
`rate_agent`	Write	Rate a public agent 1-5 stars.
`reorder_orchestrator_agents`	Write	Reorder the fraud-analysis agents assigned to an orchestrator.
`test_orchestrator`	Write	Run an orchestrator SYNCHRONOUSLY against an existing document.
`unpublish_agent`	Write	Remove one of your agents from the public marketplace.
`update_fraud_agent`	Write	Update a fraud-analysis agent / operator.
`update_orchestrator`	Write	Update an orchestrator agent.

Billing (14)

Tool	Access	Description
`cancel_billing_plan`	Destructive	Schedule cancellation of the current subscription.
`change_billing_plan`	Write	Change the organization's subscription plan.
`confirm_payment_method`	Write	Save the confirmed card as the default payment method.
`create_setup_intent`	Write	Create a Stripe SetupIntent to collect a payment method.
`download_invoice`	Read	Download an invoice as a PDF.
`get_billing_info`	Read	Get the full billing snapshot for the organization.
`get_current_usage`	Read	Get the current billing period's unbilled usage.
`get_stripe_config`	Read	Get Stripe client-side configuration.
`list_billing_plans`	Read	List all available subscription plans with pricing and features.
`list_inference_history`	Read	List the organization's AI inference / verification request history.
`list_invoices`	Read	List the organization's invoices, most recent first.
`topup_balance`	Write	Add prepaid funds to the account balance via the saved card.
`update_company_details`	Write	Update the organization's company / invoicing details.
`validate_vat_number`	Read	Validate an EU VAT number via an external lookup.

topup_balance is in US dollars, minimum $10, maximum $10,000 per top-up.

Users & Account (7)

Tool	Access	Description
`activate_trial`	Write	Save a payment method and activate the 7-day free trial with $10 credit.
`add_passkey`	Write	Begin adding a passkey to the authenticated user's account: get WebAuthn creation options.
`delete_passkey`	Destructive	Delete one of the authenticated user's passkeys.
`get_current_user`	Read	Get the authenticated user, their organization, and quick account stats.
`list_passkeys`	Read	List the authenticated user's registered passkeys.
`report_public_data`	Write	Report incorrect data in the authenticated user's public profile.
`submit_onboarding_survey`	Write	Save the current user's organization onboarding survey.

Websites (8)

Tool	Access	Description
`create_website`	Write	Create a new age-verification website configuration.
`delete_website`	Destructive	Permanently delete an age-verification website configuration.
`get_website`	Read	Get one age-verification website by ID.
`list_countries`	Read	List all countries with codes and attributes.
`list_verifications`	Read	Browse the age-verification history for the organization.
`list_websites`	Read	List every age-verification website for the authenticated organization.
`pause_website`	Write	Pause or resume age verification for a website.
`update_website`	Write	Update an existing age-verification website configuration.

Agemin Checks (3)

Tool	Access	Description
`get_age_verification_status`	Read	Re-check a prior age-verification result server-side.
`verify_age_with_email`	Write	Estimate a person's minimum age from their email address.
`verify_age_with_selfie`	Write	Estimate a person's age from a single selfie image.

Verification Sessions (16)

Tool	Access	Description
`cancel_session`	Destructive	Cancel / abort a session.
`check_email_verification`	Read	Complete email verification with the code.
`check_phone_verification`	Read	Complete phone verification with the SMS code.
`complete_liveness`	Write	Complete a face-liveness capture.
`create_session`	Write	Create a new identity-verification session.
`get_session`	Read	Show information about an open session.
`get_session_preflight`	Read	Get the next verification step for a session.
`give_session_consent`	Write	Record the applicant's consent decision.
`send_session_sms`	Write	SMS the applicant a link to continue on their phone.
`start_email_verification`	Write	Start email verification by emailing a code.
`start_liveness`	Write	Start a face-liveness capture.
`start_phone_verification`	Write	Start phone verification by texting a code.
`submit_address_verification`	Write	Upload a proof-of-address document.
`submit_funds_verification`	Write	Upload a proof-of-funds document.
`update_session`	Write	Update an open session's applicant details.
`upload_session_media`	Write	Upload captured media to a session.

API Keys (3)

Tool	Access	Description
`get_api_key`	Read	Retrieve the FULL, unmasked value of an existing API key.
`list_api_keys`	Read	List all API keys for the authenticated organization.
`rotate_api_key`	Destructive	Rotate (regenerate) an API key for the authenticated organization.

list_api_keys returns masked values; only get_api_key reveals the full secret, so keep
confirmation on for it in shared contexts. rotate_api_key keeps the old key valid for a
12-hour grace period by default; pass immediate: true to revoke it instantly.

NFC (1)

Tool	Access	Description
`submit_nfc_data`	Write	Submit NFC-scanned identity-document data to a verification session.

Server & Self-Discovery (2)

Tool	Access	Description
`describe_api`	Read	Return the Bynn REST API's OpenAPI 3.0 specification (from /openapi.json).
`describe_cli`	Read	Return install, auth, and usage instructions for the Bynn CLI (`bynn`).

Interactive widgets

Two tool families return interactive cards instead of raw JSON in hosts that support MCP
apps (ChatGPT and Claude):

Document fraud (submit_document, get_document): a live report card with the risk
gauge, forensic signals, extracted fields, and risk tags. Pending analyses poll themselves
to completion.
AI-image check (detect_ai_generated_image): verdict card with AI probability and a
generator breakdown. If no image was provided, the card renders a drag-and-drop uploader,
and the dropped file goes straight to the detector without entering the chat context.

Other MCP clients simply receive the same data as structured JSON.

Example workflow

A complete KYC session, driven conversationally:

1. "Create a verification session for applicant #4471 with my standard KYC level."
   → create_session returns {session_id, dossier_id, url, qr_base64_png, websocket_url}
2. Send the returned `url` to the applicant (or show the QR code).
3. "What's the next step for this session?"
   → get_session_preflight (after give_session_consent) walks each remaining step
4. "Show the session status."
   → get_session, repeated until the flow completes

The async pattern is the same everywhere: creation tools return an id, get_* tools poll
it. For document fraud, submit_document → get_document until status: "analyzed";
for reasoning jobs, create_reasoning_job → get_reasoning_job.

Bynn CLI: work with local files

The hosted MCP server cannot read files on your machine. The Bynn CLI can. Agents that
run locally (Claude Code, Cursor, a terminal) can analyze local files directly:

bynn submit ./bank-statement.pdf -o json      # full document-fraud analysis, auto-polls
bynn ai-generated ./profile-photo.png -o json # AI-generated-image check

Install (macOS/Linux):

brew tap Bynn-Intelligence/bynn
brew install --cask bynn

Install (Windows):

scoop bucket add bynn https://github.com/Bynn-Intelligence/scoop-bynn
scoop install bynn

Direct downloads (plus .deb/.rpm and checksums) are on the
releases page.

Authenticate once (bynn auth login stores the key in your OS keychain), or
non-interactively with BYNN_API_KEY, --token, or bynn auth login --with-token.
Sandbox keys (private_sandbox_...) are recognized automatically.

Agent-friendly by design: -o json for structured output, --jq for filtering,
--dry-run to preview requests, --poll for async results, and a clean output contract
(stdout = data, stderr = progress). The command tree is generated from the live Bynn
OpenAPI spec, and bynn api <METHOD> <PATH> is a raw authenticated passthrough to any
endpoint. The CLI covers sessions, age verification, AutoDoc invitations, documents,
moderation, NFC, and face; for billing, API keys, dossiers, orchestrators, and websites,
use this MCP server.

For agents: call the describe_cli tool on this server for this entire guide in
machine-readable form.

Self-discovery for agents

The server documents itself. If you are an LLM connected to it:

describe_api returns the complete Bynn OpenAPI 3.0 specification: every endpoint,
parameter, and schema, including ones not wrapped as MCP tools. No auth required.
describe_cli returns a structured guide to installing, authenticating, and running
the bynn CLI locally, for work against local files. No auth required.
file://server/status (MCP resource) returns the live tool list and server status.

These are also announced in the server's initialize instructions, so you don't need this
README to find them.

Advanced

Annotations and response contract

Every tool carries MCP ToolAnnotations (readOnlyHint, destructiveHint,
idempotentHint, openWorldHint), applied consistently by verb: get_*/list_*/
search_*/describe_*/download_*/validate_* are read-only; delete_*/cancel_*/
rotate_api_key are destructive. Failures come back as structured
{error: true, error_type, message} payloads rather than protocol errors, so agents can
read and react to them.

Troubleshooting

Symptom	Fix
404 / connection fails immediately	You appended `/mcp` to the URL. The endpoint is the root: `https://mcp.bynn.com`
`authentication_error` / `authentication_required`	Get a token at dashboard.bynn.com/authenticate and set it as the `Authorization` header. Don't retry blindly.
A tool returns 401 with a valid connection	Wrong credential type for that tool group; see the auth table. API keys and billing need a dashboard token, not a raw `private_` key.
Image tool says no image was provided	The card that appears accepts drag-and-drop; drop the image into it. Or pass a public `image_url`.
Document stuck in `pending`	Analysis is asynchronous; poll `get_document` until `status` is `analyzed`. Don't poll more than every few seconds.
OAuth connector stops working	Disconnect and reconnect the connector to re-run the sign-in flow.

Support

Issues and questions: github.com/Bynn-Intelligence/bynn-mcp-server
· bynn.com · dashboard.bynn.com

MIT licensed.