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()

for server in me.needs_connect:  # servers whose account you have not connected yet
    print(f"Connect {server}:", me.connect_link(server).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.1

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.1
File Size Uploaded Provenance Actions
trustgate_sdk-0.3.1.tar.gz 69.7 kB With provenance Details for trustgate_sdk-0.3.1.tar.gz

Built distribution (wheel)

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

Total release size: 121.4 kB

Release files / trustgate_sdk-0.3.1.tar.gz

Download URL trustgate_sdk-0.3.1.tar.gz
Size 69.7 kB
Tags Source
SHA-256 checksum
How to use checksums
549c07d4efd08ac7ac02f0882e109ab409aa410cad703f6721a7986cc5d4bf0e
BLAKE2b-256 checksum
How to use checksums
4835818d16bb7f533863887c1520dac804e7ff132657364564709f3c7b3249dc
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.1-py3-none-any.whl

Download URL trustgate_sdk-0.3.1-py3-none-any.whl
Size 51.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
08c449359104bf212aa21025ae2ce049fbefcebbe2b02a61e592b350a07d52df
BLAKE2b-256 checksum
How to use checksums
986b24268118d5d0c1c826dbf86665edd52c4c24ed2d948ca85a4b291bf9aad9
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.1

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.1.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