Developer SDKs

Build with the Gateco SDKs

Permission-aware retrieval in a few lines, from Python, TypeScript, the CLI, or any MCP host. Every call is checked against your policies and written to the audit trail, server-side. You ship the feature; Gateco enforces who can see what.

Python

pip install gateco

PyPI · gateco

TypeScript

npm install @gateco/sdk

npm · @gateco/sdk

CLI

gateco --help

bundled with the Python SDK

MCP server

pip install "gateco[mcp]"

stdio transport, 6 tools

Get an API key Full reference docs

Install and run your first retrieval

Install the client, authenticate, and execute a permission-aware retrieval. The same request works identically across both SDKs.

Python

pip install gateco

from gateco_sdk import GatecoClient

with GatecoClient("https://api.gateco.ai") as client:
    client.login("admin@company.com", "password")

    # Permission-aware retrieval: only chunks this principal
    # is authorized to see are ever returned.
    result = client.retrievals.execute(
        connector_id="conn_abc",
        principal_id="user_123",
        query="quarterly revenue by region",
        top_k=10,
    )
    for item in result.results:
        print(item.vector_id, item.score)

TypeScript

npm install @gateco/sdk

import { GatecoClient } from "@gateco/sdk";

const client = new GatecoClient({ baseUrl: "https://api.gateco.ai" });
await client.login("admin@company.com", "password");

const result = await client.retrievals.execute({
  connectorId: "conn_abc",
  principalId: "user_123",
  query: "quarterly revenue by region",
  topK: 10,
});
for (const item of result.results) {
  console.log(item.vectorId, item.score);
}
client.close();

Authentication

Create an API key in the app under Settings → API Keys, then provide it via environment variables. Credentials resolve in this order: GATECO_API_KEY → GATECO_BASE_URL → ~/.gateco/credentials.json.

# Option A — API key (recommended for services & the MCP server)
export GATECO_API_KEY=gk_live_...
export GATECO_BASE_URL=https://api.gateco.ai

# Option B — email + password (interactive / scripts)
#   client.login("admin@company.com", "password")

# The CLI and MCP server also read ~/.gateco/credentials.json,
# created by 'gateco login'.

Common operations

The three calls you will reach for most. TypeScript has full parity with camelCase arguments.

Secured retrieval

Run a query as a specific principal. Candidates are fetched, then each chunk is evaluated against your policies; only authorized chunks come back.

from gateco_sdk import GatecoClient

with GatecoClient("https://api.gateco.ai") as client:
    client.login("admin@company.com", "password")

    # Permission-aware retrieval: only chunks this principal
    # is authorized to see are ever returned.
    result = client.retrievals.execute(
        connector_id="conn_abc",
        principal_id="user_123",
        query="quarterly revenue by region",
        top_k=10,
    )
    for item in result.results:
        print(item.vector_id, item.score)

Grounded answer

Synthesize an answer from policy-allowed chunks only, with citations. Denied content never reaches the model. Team plan and up.

# Grounded answer (Team plan and up): synthesized only from
# chunks the principal is allowed to read, with citations.
answer = client.answers.execute(
    connector_id="conn_abc",
    principal_id="user_123",
    query="What was Q3 revenue in EMEA?",
)
print(answer.outcome)   # answered | no_access | insufficient_context
print(answer.text)
for c in answer.citations:
    print(c.vector_id, c.score)

Resolve a principal

Map a real identity (email or provider subject) to a synced Gateco principal, then use it in retrievals and answers.

# Resolve a real identity to a Gateco principal (never creates one).
principal = client.principals.resolve(email="user@company.com")
print(principal.id, principal.groups)

# Then pass principal.id to retrievals or answers above.

The `gateco` CLI

Installed with the Python SDK. Log in, resolve principals, test connectors, run retrievals, and suggest data classifications from your terminal or CI.

# The CLI ships with the Python SDK.
gateco login --email admin@company.com --password secret

# Resolve an identity, test a connector, run a retrieval
gateco principals resolve --email user@company.com
gateco connectors test conn_abc
gateco retrieve --connector-id conn_abc \
  --principal-id user_123 --query "revenue" --top-k 10

# Suggest data classifications for a connector's resources
gateco suggest-classifications conn_abc

MCP server

Give Claude Desktop, Cursor, or any MCP host policy-enforced access to your vector knowledge bases. Six tools, including retrieve and ask. Denied content is never exposed in tool output. Available on Growth and up.

MCP setup guide

pip install "gateco[mcp]"

# Run the MCP server over stdio (for Claude Desktop, Cursor, etc.)
export GATECO_API_KEY=gk_live_...
export GATECO_BASE_URL=https://api.gateco.ai
gateco mcp serve