> For the complete documentation index, see [llms.txt](https://vayl.gitbook.io/vayl-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://vayl.gitbook.io/vayl-docs/api-reference/mcp-endpoint.md).
# MCP endpoint
Send MCP JSON-RPC requests to vayl-server.
## Send an MCP JSON-RPC request
> Sends one JSON-RPC 2.0 message over MCP streamable HTTP. The server is \*\*stateless\*\*: no\
> session ID is issued, so every request stands alone.\
> \
> Common methods: \`initialize\`, \`tools/list\` (returns the 32 Vayl tools with their JSON Schemas\
> and annotations), and \`tools/call\` (runs one tool). The response is a server-sent-events\
> stream whose \`data:\` line carries the JSON-RPC response.\
> \
> A tool that is denied or fails still returns HTTP 200: the result text says\
> \`Access denied: …\` or \`Vayl couldn't complete that (ref …)\`. Find the ref in the server log\
> next to the same \`X-Request-ID\`.
```json
{"openapi":"3.1.0","info":{"title":"Vayl HTTP API","version":"0.7.0"},"tags":[{"name":"MCP","description":"The Model Context Protocol endpoint your agents connect to."}],"servers":[{"url":"http://127.0.0.1:8080","description":"Default bind address (VAYL_HOST / VAYL_PORT). Put TLS in front for anything but local use."}],"security":[{"apiKey":[]},{"oidc":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"vayl_sk_…","description":"An API key created with the `create_principal` tool. Shown once; only its hash is stored."},"oidc":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"An OIDC ID token (RS256), verified against `VAYL_OIDC_JWKS_URL` with `iss`, `aud` and `exp`\nrequired. Needs an Enterprise license granting `sso` and `pip install \"vayl-mcp[sso]\"`.\n"}},"parameters":{"RequestId":{"name":"X-Request-ID","in":"header","required":false,"description":"Correlation ID. Reused if it is 1–64 characters of `A-Z a-z 0-9 . _ : -` (so proxy and Vayl\nlogs line up); otherwise replaced with a generated one. Echoed on the response and stamped on\nevery log line written while serving the request.\n","schema":{"type":"string","maxLength":64,"pattern":"^[A-Za-z0-9._:-]{1,64}$"}}},"schemas":{"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"description":"Request id, echoed in the response. Omit for a notification.","oneOf":[{"type":"integer"},{"type":"string"}]},"method":{"type":"string","description":"The MCP method, for example `initialize`, `tools/list` or `tools/call`."},"params":{"type":"object","description":"Method parameters. For `tools/call`: `{\"name\": , \"arguments\": {…}}`."}}},"Error":{"type":"object","properties":{"error":{"type":"string"}}}},"headers":{"RequestId":{"description":"The request's correlation ID (the incoming one if it was valid, otherwise generated).","schema":{"type":"string"}}}},"paths":{"/mcp":{"post":{"tags":["MCP"],"operationId":"mcp","summary":"Send an MCP JSON-RPC request","description":"Sends one JSON-RPC 2.0 message over MCP streamable HTTP. The server is **stateless**: no\nsession ID is issued, so every request stands alone.\n\nCommon methods: `initialize`, `tools/list` (returns the 32 Vayl tools with their JSON Schemas\nand annotations), and `tools/call` (runs one tool). The response is a server-sent-events\nstream whose `data:` line carries the JSON-RPC response.\n\nA tool that is denied or fails still returns HTTP 200: the result text says\n`Access denied: …` or `Vayl couldn't complete that (ref …)`. Find the ref in the server log\nnext to the same `X-Request-ID`.\n","parameters":[{"$ref":"#/components/parameters/RequestId"},{"name":"Accept","in":"header","required":true,"description":"Must accept both JSON and server-sent events, or the server answers 406.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"A server-sent-events stream. Its `data:` line is the JSON-RPC response. Captured from\nvayl-server 0.7.0.\n","headers":{"X-Request-ID":{"$ref":"#/components/headers/RequestId"}},"content":{"text/event-stream":{"schema":{"type":"string"}}}},"401":{"description":"No credential, or one that doesn't resolve to an active principal.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}},"X-Request-ID":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The `Origin` header isn't in `VAYL_ALLOWED_ORIGINS` (DNS-rebinding protection)."},"406":{"description":"The `Accept` header doesn't include both `application/json` and `text/event-stream`."},"413":{"description":"The body is larger than `VAYL_MAX_BODY`, whether declared or chunked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"421":{"description":"The `Host` header isn't in `VAYL_ALLOWED_HOSTS`. Set it to your public host behind a proxy."},"429":{"description":"This client IP exceeded `VAYL_RATE_PER_MIN` in the last minute (per server process).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://vayl.gitbook.io/vayl-docs/api-reference/mcp-endpoint.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.