Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

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/mcp

Requests

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.

MethodUse
tools/listThe tools and their JSON input schemas
tools/callRun one tool: { "name": "...", "arguments": { ... } }
initializeProtocol handshake, for MCP clients
pingHealth check; answers {}

A message without an id is a notification: the server answers 202 with no body.

A tool call

curl
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:

  • structuredContent is the result as a JSON object. Read this one.
  • content[0].text is 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:

ScopeTools
list:projectfind_projects, get_embed_code, get_project_sections, get_section_snippet, list_libraries, get_html_import
list:project + create:projectcreate_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.