Skip to main content

trustgate-sdk

PyPI Documentation · TypeScript package · GitHub

The TrustGate SDK for Python. 3.10+, standard library only.

pip install trustgate-sdk

Setup

from trustgate import TrustGate, ToolFormat

tg = TrustGate()   # TRUSTGATE_API_KEY

The key is the whole configuration, or nothing if it is in the environment. The gateway it belongs to, and the applications behind it, are asked for: tg.identity() asks once and remembers it. Set TRUSTGATE_URL (or base_url) only for a Hybrid gateway, to the MCP host its own data plane is published on: the NeuralTrust cloud does not serve that gateway. A plain http:// address is refused unless it is this machine or you pass allow_insecure_http (TRUSTGATE_ALLOW_INSECURE_HTTP=1), because the key travels in a header.

identity = tg.identity()
# identity.key -> KeyInfo(name="prod", expires_at=None)   # None means never
# KeyConsumer(slug="support-agent", type="MCP", url="https://…/support-agent/mcp",
#             upstreams=[KeyUpstream(server="Notion", account="shared", connected=True)])
# KeyConsumer(slug="support-llm",   type="LLM", url="https://…/support-llm/v1")

key.expires_at is the 401 you would otherwise meet mid-run, and upstreams is the refusal you would otherwise meet on the first tool call — both answered before anything starts.

mcp_consumer and llm_consumer (or TRUSTGATE_MCP_CONSUMER / TRUSTGATE_LLM_CONSUMER) are only needed when a key reaches two applications on the same plane — the SDK names them and refuses rather than guessing.

An agent that acts as the application

agent = tg.connect(requires=["search"])

agent.mcp                                        # url + headers for a framework
tg.llm()                                         # base_url for OpenAI, anthropic_base_url for Anthropic
toolkit = agent.toolkit(ToolFormat.OPENAI_RESPONSES)
agent.call_tool("search", {"query": "runbook"})
agent.refresh()                                  # re-read the toolkit
agent.connections                                # its own upstream accounts

A batch that must not stop halfway:

try:
    agent = tg.connect(requires=["search"])
except UpstreamNotConnectedError as error:
    sys.exit(str(error))   # names each server and who fixes it

for row in rows:
    agent.call_tool("search", {"query": row.query})

With requires, only the servers behind those tools have to be connected: a Linear nobody connected does not stop an agent that only calls Notion. Without it, every server is one the agent may call, so any of them blocks the start.

The gateway serves a tool under the server it came from - Notion's search as notion_search - so two servers with a search stay apart. That prefix is the gateway's, so requires and call_tool take the name the server itself gave the tool and add it; naming a tool two of your servers serve is the one case they ask instead.

An agent acting for one of its users

alice = tg.for_end_user("user_123")
# or, from an agent you already have - no round trip, same toolkit:
bob = agent.for_end_user("user_456")

alice.connections()
alice.connect_link("com.notion/mcp")
alice.toolkit(ToolFormat.ANTHROPIC_MESSAGES)

A connection with shared=True holds one account for every caller: its status is that account's, and no link of the user's fixes it, so an administrator connects it in the console. connect_link(instance=connection.instance) names one of two instances of the same server.

Both handles work on the same application and the same key: who a call runs as comes from the call, not from anything configured on the application. The name is yours to choose and the gateway namespaces it, so two applications naming user_123 never reach the same account.

An agent for yourself

No application: your own Store - the servers you installed, narrowed to what Access grants you - and your models, with your personal key from the Portal (Personal key):

me = TrustGateUser(api_key="ag_...")  # or TRUSTGATE_PERSONAL_KEY
toolkit = me.connect().toolkit(ToolFormat.OPENAI_RESPONSES)  # your MCP tools
llm = me.llm()  # your models: OpenAI(base_url=llm.base_url, api_key=llm.api_key)

TrustGate(api_key=...) is an application's, and refuses a personal key with a pointer here. Or sign in through the browser instead - tools only, the models take the key:

me = TrustGate.login(url="https://acme.mcp.neuraltrust.ai/store/mcp").connect()

if me.needs_connect:  # servers whose account you have not connected yet
    print("Connect:", me.connect_link().connect_url)
toolkit = me.toolkit(ToolFormat.ANTHROPIC_MESSAGES)

The first run opens the browser; the session is kept in ~/.trustgate/sessions.json (owner-only) and renewed until the sign-in ends, a day on NeuralTrust's cloud. Then LoginRequiredError says to sign in again. cache=MemoryTokenCache() keeps nothing on disk, force=True signs in again regardless, and a backend that already holds a token uses TrustGateUser(url, access_token=...).

The model call, with tools

toolkit = agent.toolkit(ToolFormat.OPENAI_RESPONSES, strict=True)
for warning in toolkit.warnings:
    log.warning("%s could not be strict: %s", warning.tool, warning.reason)

response = client.responses.create(model="gpt-5.2", tools=toolkit.tools, input=messages)
while any(item.type == "function_call" for item in response.output):
    response = client.responses.create(
        model="gpt-5.2",
        tools=toolkit.tools,
        previous_response_id=response.id,
        input=toolkit.execute(response.output),
    )

execute() reads the provider's own objects as well as plain dicts, so the response from the OpenAI or Anthropic SDK can be passed straight in.

Your own HTTP client

tg = TrustGate(..., transport=MyTransport())

Transport is a one-method protocol. The default is UrllibTransport; the tests use a fake one. It is also where a retry policy or a proxy belongs.

Errors

Class When
MissingToolsError requires names a tool the application (or your Store) does not serve
UpstreamNotConnectedError a server the call needs has no account behind it, at startup or on a call; servers names them and the message says who connects it - never a link
ConsentRequiredError an end user has not connected; carries connect_url, checked to be a page on this gateway
LoginRequiredError a signed-in session has ended and cannot be renewed; call TrustGate.login() again
PolicyBlockedError a gateway policy refused the call
ToolNotFoundError the tool left the toolkit under a running agent, or the model named one the toolkit was not built with
PlaneUnavailableError the key reaches no application on that plane
AuthenticationError, RateLimitedError, ServiceUnavailableError, TrustGateServerError as named

Documentation

The full guide lives at docs.neuraltrust.ai:

Page What it covers
Quickstart Install, one key, connect()'s startup check, identity()
Tools The MCP endpoint for a framework, or toolkits for a provider's API
Acting for end users Per-user accounts, consent errors, connect links
Models A provider's own client pointed at the LLM plane
Configuration Every option and environment variable, Hybrid gateways, regions
Errors Every failure, and whose it is to fix

The same SDK for TypeScript: @neuraltrust/trustgate on npm. Source, examples and issues: github.com/NeuralTrust/trustgate-sdk.

Development

uv sync --extra dev
uv run pytest

CONTRIBUTING.md has every check CI runs.

Metadata

Release files for trustgate-sdk 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trustgate-sdk 0.3.0
File Size Uploaded Provenance Actions
trustgate_sdk-0.3.0.tar.gz 68.7 kB With provenance Details for trustgate_sdk-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trustgate-sdk 0.3.0
File Interpreter ABI Platform Actions
trustgate_sdk-0.3.0-py3-none-any.whl Python 3 none any Details for trustgate_sdk-0.3.0-py3-none-any.whl

Total release size: 119.8 kB

Release files / trustgate_sdk-0.3.0.tar.gz

Download URL trustgate_sdk-0.3.0.tar.gz
Size 68.7 kB
Tags Source
SHA-256 checksum
How to use checksums
8dcdd42b0967e610ce885c3e5a56541beb4a2fa3a870376725a366b2865c54df
BLAKE2b-256 checksum
How to use checksums
804142cd531db518f24c4d63e91b18dd78d6f2674606531ee142af6cc947d1c7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

Release files / trustgate_sdk-0.3.0-py3-none-any.whl

Download URL trustgate_sdk-0.3.0-py3-none-any.whl
Size 51.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8bedb9446812b937e0a100eaee98f9631001c1d73b4a65bb9725bd08f5be1353
BLAKE2b-256 checksum
How to use checksums
6cbe22542faefc41c892c71fe135b32acc2d581ce2bc23428ad2e8a107d85971
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

Security for trustgate-sdk 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for trustgate_sdk-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page