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 name | REST equivalent | Purpose |
|---|---|---|
get_capabilities | /api/v1/capabilities | Live enums (languages, doc types, tiers, add-ons). |
quote | /api/v1/quote | Binding price + ETA. |
submit | /api/v1/submit | Place 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}/packet | One matter's certified translations as an indexed exhibit packet (PDF or zip). |
verify_certificate | /api/v1/verify/{certificateId} | Public verification. |
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();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"
}
}
}'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. AGETanswers405: there is no server-to-client stream to open. - Tool hints.
submitandrefundare 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/recoveryHintenvelope and can self-correct. - Max duration 60s per HTTP call. Real translation work happens out-of-band; each tool call returns quickly.
