REST API

Everything in the MCP reference is also available over REST. Same service, same governance, same admission — a different envelope.

Use MCP if your agent framework speaks it; use REST for a script, a webhook or a language with no SDK.

Shape

POST {base}/v1/{resource}
Authorization: Bearer $VECTADYNE_TOKEN
Content-Type: application/json

Request bodies match the MCP arguments object exactly. If you can build the MCP call you can build the REST one.

Status codes

The complete set this server emits:

Status	Meaning	Retry
200	Success	—
207	Batch partly accepted	no — a success with a mixed result
400	validation	no
401	unauthenticated	no — refresh the credential
403	forbidden	no
404	not_found	no
409	conflict	no
410	gone	no
413	payload_too_large	no — shrink the batch
429	rate_limited	yes, after Retry-After
500	internal	yes, with backoff
503	dependency_unavailable	yes, with backoff

422 is never emitted. Anything not in this table is not retried, because an unknown status is an unknown cause.

The error envelope

{
  "error": {
    "code": "validation",
    "message": "scope_key must be of the form level:id",
    "field": "scope_key",
    "retryable": false,
    "request_id": "req_…",
    "details": { "example": "repo:payments" }
  }
}

retryable is the server’s judgement, not a guess from the code — honour it. field names what to fix. details.allowed carries the permitted values when the server can enumerate them.

Always log request_id. It is what makes a bug report actionable.

The MCP difference

On MCP a fault arrives as a 200 with isError: true in the tool result — the server answered, and the answer was a refusal. On REST the same refusal is an HTTP status.

So a REST client keys on status, an MCP client keys on the tool result, and a client doing both needs to read both. Same faults, same codes, two envelopes.

Rate limits

429 carries Retry-After in whole seconds. Wait it rather than applying your own backoff.

The token endpoint is different and worth knowing about: it answers with the RFC 6749 OAuth error shape (temporarily_unavailable), not this envelope, and its correlation id is only in the X-Request-Id header. A client that parses one shape everywhere will misread the other.

Discovery

curl -s "$VECTADYNE_MCP_URL" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover"}'

Unauthenticated, and the right first call: it proves reachability before a credential exists.

Next

• MCP tools · Faults · Limits