Socious Verify MCP | Socious Verify API Documentation

Socious Verify has an MCP (Model Context Protocol) server, so an AI agent — Claude, Cursor, ChatGPT, anything MCP-capable — can run identity and credential verifications for you in natural language. Ask your agent to verify a customer and it starts the verification, hands you the link for the person, watches the status and reads back the authoritative, signed result. The same tools work in agent-driven code: your Claude Code session can build an integration against sandbox and prove it end to end without leaving the terminal.

One endpoint, no SDK:

https://api.shinid.com/mcp

What your agent can do

Seven tools cover the whole relying-party flow — the same surface as the REST API, speaking the same objects:

Tool	What it does
`list_verifications`	List your verification definitions (what to verify, against which schema)
`get_verification`	One definition, with its schema and attribute conditions
`list_schemas`	Credential schemas available to verify against (KYC, phone, address, custom…)
`start_verification`	Start verifying one of your users — returns the `connect_url` to hand to the person
`check_verification`	Poll a verification attempt while the person presents their credential
`get_verification_result`	The authoritative result, keyed by verification + your customer id — act only on `VERIFIED`
`simulate_verification`	Settle a sandbox attempt as if a credential had been presented — same validation code as production

Verification definitions are created on the dashboard (Verifications → Create); the agent runs them.

Add the connector

You authenticate with the Secret Key of an integration — create one at app.shinid.com → Integrations. Start with a sandbox key (sk_test_…): it can only see and settle sandbox verifications, spends nothing, and exercises the exact validation code your live traffic will hit. Switch the key for a live one when you ship.

Claude Code

claude mcp add --transport http socious-verify https://api.shinid.com/mcp \
  --header "apikey: sk_test_YOUR_SECRET_KEY"

Then ask: “List my verifications.”

Claude Desktop / Claude web

Open Settings → Connectors → Add custom connector and paste the URL with your key:

https://api.shinid.com/mcp?apikey=sk_test_YOUR_SECRET_KEY

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "socious-verify": {
      "url": "https://api.shinid.com/mcp",
      "headers": { "apikey": "sk_test_YOUR_SECRET_KEY" }
    }
  }
}

VS Code

.vscode/mcp.json:

{
  "servers": {
    "socious-verify": {
      "type": "http",
      "url": "https://api.shinid.com/mcp",
      "headers": { "apikey": "sk_test_YOUR_SECRET_KEY" }
    }
  }
}

ChatGPT (developer mode)

Settings → Apps → Advanced → Developer mode, then add a connector by URL:

https://api.shinid.com/mcp?apikey=sk_test_YOUR_SECRET_KEY

Key hygiene. The Secret Key is a password: server-side and agent config only, never in browser code or a repo. Prefer the header form where the client supports it; the ?apikey= URL form exists for clients that only take a URL. Keys can be rotated any time from the Integrations page — delete the key and create a new one.

Ask in natural language

“Verify customer 42 with our Simple KYC verification — give me the link to send them.”

The agent calls start_verification and returns the hosted connect_url; the person opens it and presents the credential from their Socious Wallet.

“Has customer 42 passed yet?”

check_verification while the attempt is in flight, then get_verification_result for the answer to act on — VERIFIED, with the shared claims in body.

“Build the sandbox loop end to end: start a verification for test-user-1, simulate a presentation with first_name Ada, and show me the settled result.”

With a sandbox key the agent can run the whole lifecycle — including simulate_verification — without a phone or a wallet, against the same validation code production runs.

Agent-ready prompt

Bootstrapping an integration with an agent? Paste this into it:

Integrate Socious Verify into this project via its MCP server.

- Endpoint: https://api.shinid.com/mcp (streamable HTTP, JSON-RPC 2.0).
- Auth: `apikey` header carrying my Secret Key (I will provide it; never commit it).
- Discover: call list_verifications and list_schemas to see what exists.
- Flow: start_verification(verification_id, customer_id) → show connect_url to the
  person → check_verification(individual_id) to poll → get_verification_result
  (verification_id, customer_id) is the only result to act on; require status
  VERIFIED.
- Test: my key is a sandbox key — settle attempts with simulate_verification and
  prove the loop end to end before writing any production code.
- Guardrails: treat customer ids as my system's stable identifiers;
  start_verification is idempotent per (verification, customer).

Ship a working flow, then tell me which tools you called.

Protocol notes

Stateless streamable HTTP: single POST /mcp, one JSON-RPC message per request, plain JSON responses, no sessions. Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05 are accepted.
initialize and tools/list are open, so a client can connect and browse the tool catalog before you configure a key. Every tools/call authenticates.
Authorization is identical to the REST API: the key acts for your organization only, and a sandbox key is pinned to the sandbox side — it cannot see or touch live data, exactly as a Stripe test key cannot.

FAQ

Do I need an API key? Yes — the integration Secret Key from app.shinid.com → Integrations. There is no separate MCP credential; the key that drives your REST integration drives your agent.

What does it cost? The MCP server itself is free. Verifications are billed exactly as they are over REST, by your plan — see Plans, tiers and usage and pricing. Sandbox verifications are always free.

Which clients work? Anything that speaks MCP over streamable HTTP: Claude Code, Claude Desktop and web, Cursor, VS Code, ChatGPT developer mode, and any custom client built on an MCP SDK.

What can the agent touch? Only your organization’s verification data, and only on the side of the Live/Sandbox split the key belongs to. It cannot create or delete verification definitions, manage keys, or reach billing — those stay on the dashboard.

Can the agent fake a result? No. simulate_verification refuses live verifications at the model layer, and results come from credential validation, not from anything the caller asserts.

Is this different from the REST API? Same objects, same authorization, same lifecycle — see Verify a person — direct API. MCP is a second protocol onto the same surface, built for agents rather than backends.

Where do verification definitions come from? The dashboard: Verifications → Create. Pick a schema, set the conditions, and the definition is immediately visible to list_verifications.