API documentation

MCP server

Stateless streamable-HTTP MCP endpoint at https://www.verdacert.com/api/mcp. Eight tools mirrored 1:1 onto the REST surface. Works with Claude Desktop, Cursor, OpenAI Agent SDK, the Vercel AI SDK's MCP client, and any other MCP-aware runtime.

Why MCP?

When you control the agent runtime, MCP is the lowest-friction way to give it new tools - no SDK install, no JSON-schema definitions, no per-tool wiring.

Drop one block of config into Claude Desktop or Cursor (or any conformant client) and Verdacert's eight tools show up in the tool picker. The agent calls them as if they were native. You get the same idempotency, rate limiting, structured errors, and signed certificates as the REST API - same backend.

Available tools

Identical semantics to the REST endpoints; consult /docs/api for full request/response shapes.

MCP tool nameREST equivalentPurpose
get_capabilities/api/v1/capabilitiesLive enums (languages, doc types, tiers, add-ons).
quote/api/v1/quoteBinding price + ETA.
submit/api/v1/submitPlace the order.
get_status/api/v1/status/{jobId}Poll progress.
get_result/api/v1/result/{jobId}Fetch certified artifact + JWS receipt.
refund/api/v1/refund/{jobId}Full or partial refund within the 30-day window.
get_case_packet/api/v1/matters/{reference}/packetOne matter's certified translations as an indexed exhibit packet (PDF or zip).
verify_certificate/api/v1/verify/{certificateId}Public verification.
Refunds via MCP
refund calls the same backend as REST and is safe to retry: the same arguments return the same refund, with replayed: true. Full refund by default; pass amountCents for partial, and a new idempotencyKey for a second refund of the same amount. The 30-day window from order creation applies in both environments. Agents should treat refund as a sensitive action - confirm intent with your end-user before issuing it.

Claude Desktop

Claude Desktop's config file runs local servers only, so reach the remote endpoint through the mcp-remote bridge, which passes your key as a header. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (or the Windows equivalent at %APPDATA%\\Claude\\claude_desktop_config.json) and restart Claude Desktop. Node.js must be installed for npx.

{
  "mcpServers": {
    "verdacert": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://www.verdacert.com/api/mcp",
        "--header",
        "Authorization:${VERDACERT_AUTH}"
      ],
      "env": {
        "VERDACERT_AUTH": "Bearer vc_sandbox_…"
      }
    }
  }
}

The key sits in env rather than in args because some clients split arguments on the space in Bearer vc_…. Confirm the integration by asking Claude something like: “Can you call Verdacert and tell me which languages you can certify translations for?” Claude should call get_capabilities automatically.

Claude Code

Claude Code connects to remote servers directly. Add Verdacert once from your terminal:

claude mcp add --transport http verdacert https://www.verdacert.com/api/mcp \
  --header "Authorization: Bearer vc_sandbox_…"

Cursor

Cursor connects to remote servers directly. Add this to ~/.cursor/mcp.json (or the project's .cursor/mcp.json), or paste it under Settings → MCP → Add new MCP server.

{
  "mcpServers": {
    "verdacert": {
      "url": "https://www.verdacert.com/api/mcp",
      "headers": {
        "Authorization": "Bearer vc_sandbox_…"
      }
    }
  }
}

The tools show up in Cursor's in-chat tool picker immediately. Test the connection by typing /verdacert in chat to surface the tools.

Vercel AI SDK (MCP client)

The AI SDK has a built-in MCP client if you'd rather consume MCP than install our typed tools package.

import { generateText } from "ai";
import { createMCPClient } from "@ai-sdk/mcp";

// "http" is the streamable-HTTP transport this server speaks. The older
// "sse" transport waits on a GET stream the server doesn't offer.
const mcp = await createMCPClient({
  transport: {
    type: "http",
    url:  "https://www.verdacert.com/api/mcp",
    headers: {
      Authorization: `Bearer ${process.env.VERDACERT_API_KEY}`,
    },
  },
});

const tools = await mcp.tools();

const { text } = await generateText({
  model: "anthropic/claude-sonnet-5.5",
  tools,
  prompt: "Quote a 3-page Farsi birth certificate for USCIS.",
});

await mcp.close();
Prefer @verdacert/ai-sdk-tools for TypeScript apps
Our typed AI SDK package wraps the REST API directly - zero MCP runtime, full TypeScript types end-to-end, and slightly lower latency. Use MCP when you want one config to feed an end-user-facing agent runtime (Claude Desktop, Cursor). See /docs/ai-sdk.

Raw JSON-RPC

If you're integrating from a runtime without an MCP library, the wire format is plain JSON-RPC 2.0 over POST.

List tools

curl https://www.verdacert.com/api/mcp \
  -H 'Authorization: Bearer vc_sandbox_…' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id":      1,
    "method":  "tools/list",
    "params":  {}
  }'

Call a tool

curl https://www.verdacert.com/api/mcp \
  -H 'Authorization: Bearer vc_sandbox_…' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id":      2,
    "method":  "tools/call",
    "params": {
      "name":      "quote",
      "arguments": {
        "sourceLanguage": "fa",
        "useCase":        "uscis",
        "pageCount":      2,
        "speedTier":      "standard"
      }
    }
  }'
Required headers
The MCP transport requires Accept: application/json, text/event-stream even though responses are single JSON bodies (the stateless server uses enableJsonResponse: true). Some MCP clients add this automatically; raw HTTP clients must set it.

Behavior & limits

What an MCP-using agent sees vs. a REST client.

  • Stateless. No session id; each JSON-RPC request stands alone. Combined with enableJsonResponse: true, every response is a single JSON body - no SSE stream to manage. A GET answers 405: there is no server-to-client stream to open.
  • Tool hints. submit and refund are marked destructive (they move money); the other five are marked read-only, so clients that auto-approve reads can run them without asking.
  • Authenticated once per request. The same Bearer header authenticates each call; revoke a key and MCP access stops within the request.
  • Rate limited. Same 300 req/min per-key limit as REST. Tool calls inside a single agent loop count individually.
  • Structured errors bubble up through the MCP tool-result channel - agents see the same code / message / recoveryHint envelope and can self-correct.
  • Max duration 60s per HTTP call. Real translation work happens out-of-band; each tool call returns quickly.

Where to next

Get instant quotePricing