<!-- source: https://vectoralix.com/docs/clients/custom | service: Vectoralix | format: markdown twin auto-generated from the canonical HTML page -->

Client Integrations

#  Custom Clients (SDK) 

 Build a custom integration — chatbot, internal agent, or CLI — that speaks Streamable HTTP MCP against a Vectoralix endpoint. The protocol is JSON-RPC 2.0 over HTTP; the official SDKs do most of the heavy lifting, leaving you to inject the URL and Bearer token.

 ## Protocol recap

- Transport: Streamable HTTP. POST carries client-to-server JSON-RPC messages, GET opens an SSE stream for server-pushed events, DELETE closes a session.
- Endpoint: https://vectoralix.com/mcp/&lt;serverUid&gt;
- Auth on private servers: Authorization: Bearer &lt;endpoint-token&gt;. Public servers accept anonymous requests.
- Body: JSON-RPC 2.0. The official SDKs frame messages, manage session IDs, and surface tool/resource lists for you.
 
## Recommended SDKs

 Use the official Model Context Protocol SDKs as your starting point. They handle JSON-RPC framing, session resumption, and the Streamable HTTP transport details, leaving you to plug in the URL and the Bearer token.

- TypeScript: @modelcontextprotocol/sdk
- Python: mcp
 
 API surfaces of these SDKs evolve frequently. The snippets below show the canonical pattern — instantiate an HTTP transport against the Vectoralix URL, inject the Authorization header, list tools, call one — and should be adapted to the exact class names of the SDK version you install.

## TypeScript example

```
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const transport = new StreamableHTTPClientTransport(
  new URL("https://vectoralix.com/mcp/<serverUid>"),
  {
    requestInit: {
      headers: {
        Authorization: "Bearer <endpoint-token>",
      },
    },
  },
);

const client = new Client({ name: "my-agent", version: "1.0.0" }, {});
await client.connect(transport);

const tools = await client.listTools();
console.log(tools);

const result = await client.callTool({
  name: "search_files",
  arguments: { query: "billing" },
});
console.log(result);
```

## Python example

```
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

url = "https://vectoralix.com/mcp/<serverUid>"
headers = {"Authorization": "Bearer <endpoint-token>"}

async with streamablehttp_client(url, headers=headers) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()

        tools = await session.list_tools()
        print(tools)

        result = await session.call_tool(
            "search_files",
            {"query": "billing"},
        )
        print(result)
```

## Error handling

    HTTP status Meaning What the client should do     401 Private server: missing, wrong, or expired endpoint token. Returned for unknown serverUid too, by design, to prevent UID enumeration. Re-fetch the token from the dashboard; verify the URL's serverUid character-by-character.   404 Public server: serverUid does not match any server. Private servers do not return 404. Confirm the URL was copied from the dashboard and the server is still public.   429 Rate limit exceeded — per-server, per-month bucket per the plan. Honor the rate-limit headers; back off and retry, or escalate the plan.   5xx Server-side failure: missing active version, tool execution error, or internal exception. Inspect the JSON-RPC error body for an error stage badge — ssrf, http, or post\_processing — to localize the failure.    Tool-level errors travel inside the JSON-RPC response as an error object — the HTTP status is still 200. The SDKs surface these as exceptions or error fields on the result; do not assume HTTP 200 means the tool succeeded.

## Session reuse vs one-shot calls

 Reuse one ClientSession across many tool calls when you can — initialize once, then call tools as needed. The Streamable HTTP transport keeps a session id between requests, which is cheaper than re-initializing for every call. Rate-limit buckets are keyed per MCP server per month, not per session, so reusing a session does not save quota — it saves round-trips.

## Resources alongside tools

 In addition to tools, Vectoralix exposes each piece of version content as an MCP resource at content://&lt;slug&gt; with MIME type text/plain. Clients that speak the resources side of the protocol can list and read them directly; tool-only clients reach the same content through the File Search capabilities instead.

## When the MCP protocol is not enough

 Anything that is not a tool call — programmatically listing the MCP servers in your organization, managing versions, rotating endpoint tokens — lives outside MCP, on the Vectoralix REST API. The Authentication &amp; API group documents that surface and is the right starting point for management automation.