Calling Tools over HTTP
You don't need an MCP client library to use the Vev MCP server. It is plain JSON-RPC 2.0 over HTTPS, so any server or script that can send a POST can call its tools. This page shows the exact requests and responses.
POST https://api.vev.design/v2/mcpRequests
Send one JSON-RPC message per request, with Content-Type: application/json and your credentials:
- an API key in
x-vev-key: [your-key], or - an OAuth access token (which is also an API key) in
Authorization: Bearer [token]. See Connect Your App with OAuth.
The server is stateless. There is no session to open and no Mcp-Session-Id header to keep, so tools/call works as the first request. initialize is supported for MCP clients that expect it, but you can skip it. Batches (a JSON array of messages) are refused.
| Method | Use |
|---|---|
tools/list | The tools and their JSON input schemas |
tools/call | Run one tool: { "name": "...", "arguments": { ... } } |
initialize | Protocol handshake, for MCP clients |
ping | Health check; answers {} |
A message without an id is a notification: the server answers 202 with no body.
A tool call
curl https://api.vev.design/v2/mcp \
--header "x-vev-key: [your-key]" \
--header "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "find_projects",
"arguments": { "search": "summer campaign", "limit": 3 }
}
}'Responses
Responses are bare JSON-RPC. They are not wrapped in the { "success": ..., "data": ... } envelope that the REST API uses. A successful call returns the result twice:
structuredContentis the result as a JSON object. Read this one.content[0].textis the same JSON as a string, for MCP clients that only show text.
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [{ "type": "text", "text": "{\n \"projects\": [ ... ]\n}" }],
"structuredContent": {
"projects": [
{
"key": "AbC123xyz45",
"title": "Summer campaign 2026",
"published": true,
"publishedAt": 1779184000000,
"updated": 1779270400000,
"thumbnailUrl": "https://api.vev.page/image/thumb/AbC123xyz45/Hk2Pq9",
"editorUrl": "https://editor.vev.design/edit/AbC123xyz45"
}
],
"notFound": []
}
}
}Errors
There are three kinds of failure, and each comes back in a different place.
The tool refused (bad input, no access, not enough AI balance, a missing scope). The HTTP status is 200 and the result has isError: true, with a readable message in content[0].text. There is no structuredContent. Show the message to your user or fix the call.
{
"jsonrpc": "2.0",
"id": 7,
"result": {
"content": [{ "type": "text", "text": "Page Hk2Pq9 not found in project AbC123xyz45" }],
"isError": true
}
}A connection without a scope a tool needs gets this kind of result too, and the message asks to reconnect:
{
"content": [{
"type": "text",
"text": "import_html_section needs the create:project scope, which this connection was not granted. Reconnect the Vev MCP server and approve the additional access."
}],
"isError": true
}The message itself is wrong (an unknown tool or method, or a body that isn't JSON-RPC). The HTTP status is 200 and the response has a JSON-RPC error with a code, for example -32602 for an unknown tool or -32601 for an unknown method.
{ "jsonrpc": "2.0", "id": 3, "error": { "code": -32602, "message": "Unknown tool: find_project" } }The credentials are missing, invalid or revoked. The HTTP status is 401, with a WWW-Authenticate header that points at the OAuth metadata. With an OAuth connection this means the user revoked the key, so send them through connecting again.
Scopes
Every tool needs list:project. Tools that create or change content also need create:project:
| Scope | Tools |
|---|---|
list:project | find_projects, get_embed_code, get_project_sections, get_section_snippet, list_libraries, get_html_import |
list:project + create:project | create_project, create_page, list_library_sections, create_page_from_data, update_sections, import_html_section |
Tools return only what the authenticated user can access. Tools that write also check that the user can edit the project.
For full calls to every tool, see Examples.