MCP

Vadyl's MCP endpoint is a canonical projection of the same operation dispatcher used by REST, SDKs, CLI, and dashboard actions. There is no separate AI-only authority path.

Endpoints

POST /mcp/{tenantSlug}/{projectSlug}
GET  /mcp/{tenantSlug}/{projectSlug}/.well-known/oauth-protected-resource

Supported JSON-RPC methods

Protected resource metadata

GET /mcp/acme/billing/.well-known/oauth-protected-resource

HTTP/1.1 200 OK
{
  "resource": "https://api.vadyl.app/mcp/acme/billing",
  "authorization_servers": ["https://api.vadyl.app/oauth"],
  "scopes_supported": [
    "vadyl:project:read",
    "vadyl:operation:invoke",
    "vadyl:agent:run"
  ],
  "bearer_methods_supported": ["header"]
}

List tools

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/list",
  "params": {}
}

Call a tool

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "tools/call",
  "params": {
    "name": "Order.list",
    "arguments": {
      "filter": { "status": { "eq": "paid" } },
      "pageSize": 5
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": "2",
  "result": {
    "content": [{
      "type": "json",
      "json": {
        "data": [{ "id": "ord_123", "status": "paid" }],
        "page": { "size": 5, "next": "cur_1" }
      }
    }]
  }
}

Initialize

{
  "jsonrpc": "2.0",
  "id": "init-1",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "clientInfo": { "name": "acme-agent", "version": "1.3.0" },
    "capabilities": {
      "tools": {},
      "resources": {},
      "prompts": {},
      "completion": {}
    }
  }
}

Tool families

Resources

{
  "jsonrpc": "2.0",
  "id": "res-1",
  "method": "resources/list",
  "params": { "cursor": null }
}

Read resource

{
  "jsonrpc": "2.0",
  "id": "res-2",
  "method": "resources/read",
  "params": { "uri": "vadyl://schema/entities/Order" }
}

{
  "jsonrpc": "2.0",
  "id": "res-2",
  "result": {
    "contents": [{
      "uri": "vadyl://schema/entities/Order",
      "mimeType": "application/json",
      "text": "{\"name\":\"Order\",\"fields\":[\"id\",\"status\",\"total\"],\"operations\":[\"list\",\"read\",\"create\",\"update\",\"refund\"]}"
    }]
  }
}

Prompts

{
  "jsonrpc": "2.0",
  "id": "prompt-1",
  "method": "prompts/list",
  "params": {}
}

{
  "jsonrpc": "2.0",
  "id": "prompt-1",
  "result": {
    "prompts": [{
      "name": "debug-slow-operation",
      "description": "Inspect query plan, cache decision, provider health, and recent traces for one operation.",
      "arguments": [
        { "name": "operation", "required": true },
        { "name": "since", "required": false }
      ]
    }]
  }
}

Completion

{
  "jsonrpc": "2.0",
  "id": "complete-1",
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/resource", "uri": "vadyl://schema/entities/" },
    "argument": { "name": "entity", "value": "Or" }
  }
}

{
  "jsonrpc": "2.0",
  "id": "complete-1",
  "result": {
    "completion": {
      "values": ["Order", "OrderLine", "OrderRefund"],
      "total": 3,
      "hasMore": false
    }
  }
}

Projection rules

• Every project-visible canonical operation can become an MCP tool when the exposure grants allow it.
• Tool input schemas derive from the same request contracts as REST/OpenAPI/SDK/CLI.
• Tool output schemas derive from canonical response contracts and preserve error envelopes.
• Agent runs, memory recall, knowledge corpus retrieval, and operation dispatch are all audited and metered.
• Denied tools are absent from tools/list for that token.
• Resource reads are publication-pinned, field-security aware, and redacted under the same access masks as REST reads.
• Prompt templates are generated from project descriptors, installed surfaces, and agent definitions; they do not grant extra authority.

Auth, scopes, and headers

Rate limits and quotas

• tools/list, resources/list, and prompts/list use descriptor-cache quotas and return stable cursors.
• tools/call consumes the same operation quota, token budget, connector quota, workflow quota, and billing meter as the underlying surface.
• Agent tools run token-accounting preflight before model calls and reconcile final spend after completion.
• Long-running tools return an accepted run resource when the operation cannot complete inside the synchronous window.
• Retries must reuse the same JSON-RPC id plus the underlying idempotency key when the tool declares one.

Observability

{
  "vadyl": {
    "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42",
    "publicationVersion": 412,
    "bindingId": "mcp:tool:Order.list",
    "descriptorHash": "sha256:8b7a...",
    "reasonCodeBlock": "Mcp.ToolDispatch",
    "usage": {
      "meter": "operation.invoke",
      "tokensEstimated": 0,
      "providerCalls": 1
    }
  }
}

Error response

{
  "jsonrpc": "2.0",
  "id": "2",
  "error": {
    "code": -32003,
    "message": "Access denied",
    "data": {
      "vadylCode": "ACCESS_DENIED",
      "reasonCode": "Mcp.ToolGrant.Missing",
      "correlationId": "01HXZ0J4YV8AJF2GFG2T1F7Y42"
    }
  }
}