Custom Clients (SDK)

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/<serverUid>
• Auth on private servers: Authorization: Bearer <endpoint-token>. 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://<slug> 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 & API group documents that surface and is the right starting point for management automation.