OverviewDocsGuides

Agent SDK API Reference

Every method on PharosClient, plus the security layer that guards every call.

PharosClient

The central class for both SDKs. Construct it once, then call any of the methods below. Python and TypeScript signatures are shown together for each method.

search

Search the registry. Pass a natural-language query, optional filters (category, runtime, scope), and a result limit. Returns ranked server cards ready to connect.

Python
search(text: str, filters: dict = None, limit: int = 10) -> list[dict]
TypeScript
search(text: string, filters?: Record<string, unknown>, limit?: number): Promise<Server[]>

get_server

Get the full server card for a single server by name, including metadata, capabilities, and the latest version manifest.

Python
get_server(name: str) -> dict
TypeScript
getServer(name: string): Promise<Server>

connect_and_approve

Connect with the full approval flow. The SDK sets up the transport, negotiates the requested capabilities, runs the security checks, and prompts the user for explicit consent. Returns an open Connection you can call tools through.

Python
connect_and_approve(server: dict, capabilities: list = None) -> Connection
TypeScript
connectAndApprove(server: Server, options?: { capabilities?: string[] }): Promise<Connection>

revoke

Revoke all access to a server. Removes the connection, clears the consent entry, and unpins the server key. The agent can no longer call tools on that server without a fresh approval.

Python
revoke(server_name: str) -> None
TypeScript
revoke(serverName: string): Promise<void>

check_scope

Check whether a specific scope (e.g. "read", "write", "tools") is currently granted for a server. Use this before attempting an operation that requires elevated access.

Python
check_scope(server_name: str, scope: str) -> bool
TypeScript
checkScope(serverName: string, scope: string): Promise<boolean>

Security layer

Every connection passes through four security checks before the agent can call a tool. These run automatically inside connect_and_approve but each is also available to inspect directly.

Blocklist checking

Before any connection, the SDK consults a maintained blocklist of known-malicious or recalled servers. A match short-circuits the connect call and raises a BlocklistedError.

Key pinning

On first successful connection, the SDK pins the server's public key. Subsequent connections reject any key mismatch, preventing man-in-the-middle attacks even if the registry is compromised.

Approval engine

The engine evaluates the requested capabilities against the server's declared risk levels. High-risk operations (file write, network egress, shell exec) always require explicit user approval. Low-risk operations can be auto-approved if the user's policy allows it.

Consent store

Every granted scope is recorded per server in a local consent store. check_scope reads from it, revoke clears it, and the approval engine writes to it. The store is the single source of truth for what an agent may do.

Putting it together

Python
from pharos_discovery import PharosClient

client = PharosClient()

# Search and connect
results = client.search("filesystem", limit=5)
server = client.get_server(results[0]["name"])
conn = client.connect_and_approve(server, capabilities=["tools"])

# Check a scope before using it
if client.check_scope(server["name"], "read"):
    print("ready to read")
TypeScript
import { PharosClient } from "@pharos/sdk";

const client = new PharosClient();

// Search and connect
const results = await client.search("filesystem", undefined, 5);
const server = await client.getServer(results[0].name);
const conn = await client.connectAndApprove(server, {
  capabilities: ["tools"],
});

// Check a scope before using it
if (await client.checkScope(server.name, "read")) {
  console.log("ready to read");
}
Overview Guides