Connectors

Connectors are how application or agent traffic reaches Pelorus. They let you route queries through enabled datasets so Pelorus can return chunks, Query Extracts, or Cluster Extracts while observing demand.

Python client

Use the Python client when application code should send runtime queries to a local or remote Pelorus engine. The default client surface is intentionally small: connect, query, look up an Extract, inspect read-only state, and close the connection.

from pelorus import PelorusClient

pq = PelorusClient.connect("http://127.0.0.1:9090")
result = pq.query("Which warranty terms apply?", dataset="support")

for document in result.documents:
    print(document.metadata.get("type"), document.content[:160])

Dataset setup, diagnostics, and development controls live on client.dev(). Keeping them separate makes it clear which calls belong in application request paths and which calls are for setup, tests, or operations.

from pelorus import Pelorus

with Pelorus.local(config="config.yaml") as pq:
    dev = pq.dev()
    dataset = dev.create_managed_dataset(
        name="support-docs", source_folder="/data/support-docs"
    )

    # A new dataset lands disconnected. Connect binds it to a datasource group
    # and creates its vectors; enable is a pure gate that turns serving on.
    dev.connect_dataset_group(dataset["id"], group_id, vector_policy="reuse_valid")
    dev.enable_dataset(dataset=dataset["id"])

    answer = pq.query("How do returns work?", dataset=dataset["id"])

group_id is the id of a datasource group, which you create in the admin console. Every dataset in a group shares one immutable embedding configuration, so its vectors are all in the same embedding space. If that configuration later changes, the dataset reads Re-embed Required and is held back from serving until you reconnect it with vector_policy="revectorize_all".

Read-only notebook and reporting workflows use client.analysis() to pull Query Maps, clusters, vectors, coverage, and similarity data without mutating the dataset.

See Client API for the current Python client and MCP-facing method signatures.

Download the example notebook: Pelorus Demand Coverage Audit.

MCP

Use the MCP connector when an MCP-capable agent should query Pelorus, inspect runtime state, or ask Pelorus to answer a question. MCP lets an agent workflow use the same dataset and retrieval surface without embedding Pelorus directly into the agent process.

pelorus-mcp --url http://127.0.0.1:9090 --transport stdio

The MCP tools are intentionally a thin facade over the Python client. Agents can query, poll Extract state, inspect dataset state, and submit or list extraction demand. MCP is a client API: it never hands extraction work to the agent. In the developer release, this is a trusted-local workflow: the connector does not implement authentication, so run it on localhost, a private machine, or behind your own access boundary.

Configure Claude Code

Start the Pelorus management API first, then let Claude Code launch pelorus-mcp as a local stdio MCP server.

python -m pelorus.serve --config config.yaml --host 127.0.0.1 --port 9090
claude mcp add pelorus -- pelorus-mcp --url http://127.0.0.1:9090 --transport stdio

For a shared project configuration, put this in .mcp.json at the project root. Claude Code will ask you to approve the server the first time the project opens it; use /mcp inside Claude Code to confirm that pelorus is connected.

{
  "mcpServers": {
    "pelorus": {
      "type": "stdio",
      "command": "pelorus-mcp",
      "args": ["--url", "http://127.0.0.1:9090", "--transport", "stdio"]
    }
  }
}

Who authors Extracts

Pelorus authors every Query Extract and Cluster Extract itself, with its configured extract LLM. Extract Processing is the one place Pelorus calls an LLM, and by default it does so with an API key you configure. MCP does not change that: an agent connected over MCP can request Extracts, but never writes them.