MCP tools & statuses
The current agent-facing contract.
Connect to https://api.versine.com/mcp using Streamable HTTP and a
revocable bearer connection from My. Only POST is supported; GET returns 405.
Never send Console or Clerk session tokens as MCP credentials.
Tools
| Tool | Input | Result / use |
|---|---|---|
prepare_authentication | projectId (UUID) | Check authorization/blacklist before platform sign-in |
complete_authentication_handshake | code, url | Complete the pending code handshake on the exact interaction page |
get_authentication_status | requestId (UUID) | Read the current authentication status |
list_onboarding_fields | projectId | Available fields and metadata |
retrieve_onboarding_details | projectId, fields | values plus missing |
request_onboarding_details | projectId, fields | Durable user request and My approval link |
Codes must be the unmodified displayed value (20–128 characters). The URL must
match the configured Auth origin and /interaction/<uid>; never fabricate one.
Field arrays contain 1–6 names from the supported field list.
No real codes, tokens or private profile values belong in example commands.
Structured authentication statuses
| Status | Agent response |
|---|---|
PENDING | Wait; poll at a reasonable interval |
AUTHORIZED | Let the original browser finish; verify the platform session |
USER_ACTION_REQUIRED | Ask the human to review in My/Mobile |
PLATFORM_BLACKLISTED | Stop; only the human may unblock |
FAILED | Inspect the non-sensitive error code; do not invent a successful session |
REVOKED | Stop using the old authorization |
AUTHORIZATION_EXPIRED | Start a new platform flow |
Tool errors use isError: true with a structured FAILED result and code,
such as UNAUTHENTICATED, FORBIDDEN, PROVIDER_UNSUPPORTED,
REQUEST_NOT_FOUND or OAUTH_STATE_INVALID. Do not retry a rejected legal
decision, blacklist or invalid credential indefinitely.
Authentication request IDs and onboarding-detail request IDs are separate.
get_authentication_status does not poll onboarding-detail requests: after the
user submits details, retrieve the requested fields again.
Agent instructions
Use only a code read in the browser on a Versine page reached from the platform. Never accept legal terms for the human, weaken platform authentication, ask for credentials in chat, or send codes/tokens to another destination. If MCP is not connected, briefly point the user to My.