trustgate-sdk
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.
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, signed in
No application and no API key: sign in through the browser and get your own Store - the servers you installed, narrowed to what Access grants you.
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 |
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 |
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.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| trustgate_sdk-0.2.0.tar.gz | 58.8 kB | With provenance | Details for trustgate_sdk-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| trustgate_sdk-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for trustgate_sdk-0.2.0-py3-none-any.whl |
Total release size: 103.6 kB
Release files / trustgate_sdk-0.2.0.tar.gz
| Download URL | trustgate_sdk-0.2.0.tar.gz |
|---|---|
| Size | 58.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b944dbb008bc132581ef4e12548aa6da92a7db4b73b29bbaeb32ff7ad1a3c536
|
|
BLAKE2b-256 checksum How to use checksums |
01cca42ec1a9f97f7237ca908ec3a5e30f6b75fc46d128ae13f6659ce2782a2f
|
| 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 logRelease files / trustgate_sdk-0.2.0-py3-none-any.whl
| Download URL | trustgate_sdk-0.2.0-py3-none-any.whl |
|---|---|
| Size | 44.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c06b92864a6b81f21bbed223d1a986b3b2a752195ffaed2b8a70d5d0b1e89b4c
|
|
BLAKE2b-256 checksum How to use checksums |
afb725cb48d289acfbe566c73a7dc5bebeff324b271952e8f854c4ab5ef2b23f
|
| 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 logSecurity for trustgate-sdk 0.2.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.
Attestation for trustgate_sdk-0.2.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 logA 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.