Developer reference

V8Chat MCP interface

Technical contract for connecting MCP-compatible clients and agents to V8Chat. Personal self-service keys are workspace-bound; partner service tokens can use organization routing where permitted.

MCP overview User documentation Server metadata

Quick facts

Endpoint: https://api.v8chat.com/mcp
Transport: streamable-http
Metadata: https://api.v8chat.com/.well-known/mcp/server.json
Auth: Authorization: Bearer <token>
Modern protocol: 2026-07-28
Legacy fallback: 2025-11-25

Authentication

Self-service users create a personal access key in Member → AI connections (MCP). Send it as a Bearer token. The complete key is shown once and V8Chat stores only its SHA-256 hash. Partner service tokens use the same Bearer header; legacy X-Partner-* headers remain supported for partner integrations.

Self-service key prefixv8m_…

Supported protocol generations

Modern: 2026-07-28

server/discover is used for discovery. For modern requests V8Chat validates MCP-Protocol-Version and requires Mcp-Method; tools/call additionally requires Mcp-Name to match the JSON-RPC body.

Legacy fallback: 2025-11-25

initialize remains available for older clients. The response includes a Mcp-Session-Id. Clients should prefer the modern generation where supported.

Discovery and lifecycle

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}'

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

Tools

v8chat.search

Input: { query: string, limit?: 1..10 }

Finds capabilities enabled for the authenticated context.

v8chat.describe

Input: { capability: string }

Returns the input contract for one enabled capability before execution.

v8chat.execute

Input: { capability: string, input: object, options?: object, idempotency_key?: string, organization_id?: string }

Executes the capability through the shared V8Chat runtime. organization_id is partner-only; self-service access is already workspace-bound.

v8chat.status

Input: { job_id: string, organization_id?: string }

Reads the status of asynchronous jobs returned by execution.

Request examples

Generic client configuration

{
  "mcpServers": {
    "v8chat": {
      "url": "https://api.v8chat.com/mcp",
      "headers": {
        "Authorization": "Bearer v8m_…"
      }
    }
  }
}

Search

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Authorization: Bearer v8m_…' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: v8chat.search' \
  --data '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"v8chat.search","arguments":{"query":"translate text","limit":5}}}'

Execute

curl -sS 'https://api.v8chat.com/mcp' \
  -H 'Authorization: Bearer v8m_…' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/call' \
  -H 'Mcp-Name: v8chat.execute' \
  --data '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"v8chat.execute","arguments":{"capability":"translate.text","input":{"text":"Hello","to":"de"},"idempotency_key":"client-123"}}}'

Legacy initialize body

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}

Errors and retry behavior

Protocol errors use JSON-RPC error objects. Authentication and policy errors also carry HTTP status codes. 429, 502, 503 and 504 are considered retryable; Retry-After is sent when available.

Code	Meaning
`mcp_self_service_disabled`	Personal MCP access is off for the account.
`invalid_mcp_token`	The Bearer token is invalid, revoked or no longer usable.
`workspace_access_required`	The user no longer has access to the token workspace.
`organization_mismatch`	The requested organization/workspace does not match the authenticated scope.
`mcp_header_mismatch`	Modern MCP routing headers do not match the JSON-RPC request.
`unsupported_mcp_version`	The requested protocol version is not supported.

Security and scope

Self-service MCP is off by default per user.
Personal keys are bound to one user and one V8Chat workspace.
Disabling MCP blocks existing personal keys immediately.
Rotating a key revokes previous active keys for that user/workspace.
Execution reuses the same capability, policy, idempotency and job runtime as the partner REST interface.
For self-service keys, organization_id is ignored as a routing mechanism and cannot be used to switch workspaces.