Documentation · Python package · GitHub
The TrustGate SDK for TypeScript. Node 22+, no runtime dependencies. ESM only:
import it, or require() it from Node 22.12.
npm install @neuraltrust/trustgateimport { TrustGate, ToolFormat } from '@neuraltrust/trustgate'
const tg = new TrustGate() // TRUSTGATE_API_KEYThe 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 baseUrl)
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 allowInsecureHttp
(TRUSTGATE_ALLOW_INSECURE_HTTP=1), because the key travels in a header.
const { gateway, key, consumers } = await tg.identity()
// key: { name: 'prod', expiresAt: Date | undefined } — undefined means never
// consumers:
// [{ slug: 'support-agent', type: 'MCP', url: 'https://…/support-agent/mcp',
// upstreams: [{ server: 'Notion', account: 'shared', connected: true }] },
// { slug: 'support-llm', type: 'LLM', url: 'https://…/support-llm/v1' }]key.expiresAt 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.
mcpConsumer and llmConsumer (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.
const agent = await tg.connect({ requires: ['search'] })
agent.mcp // { url, headers } for a framework
await tg.llm() // baseUrl for OpenAI, anthropicBaseUrl for Anthropic
agent.toolkit(ToolFormat.OpenAIResponses) // { tools, execute, warnings }
await agent.callTool('search', { query: 'runbook' })
await agent.refresh() // re-read the toolkit
agent.connections // its own upstream accountsWith 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 callTool 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.
const alice = await tg.forEndUser('user_123')
// or, from an agent you already have — no round trip, same toolkit:
const bob = agent.forEndUser('user_456')
await alice.connections()
await alice.connectLink('com.notion/mcp')
alice.toolkit(ToolFormat.AnthropicMessages)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. connectLink({ 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. Each user needs their own handle because the MCP endpoint fixes its headers when a client connects, and the user travels in one.
The name is yours to choose and the gateway namespaces it, so two applications
naming user_123 never reach the same account.
await tg.agents() // every agent the key reaches
const planner = await tg.agent('Travel planner', { endUser: 'user_123' })
// { id, name, cardUrl, protocolVersion, url, headers, consumer }The SDK does not speak A2A: an A2A client (@a2a-js/sdk) takes cardUrl and
headers, and both the card and the calls go through the gateway with them.
url is the agent's JSON-RPC endpoint. endUser adds the same header as
forEndUser. A name two agents share throws (code: 'ambiguous_agent'); use
the id. An unknown one throws code: 'agent_not_found' and lists what the key
reaches.
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):
const me = new TrustGateUser({ apiKey: process.env.TRUSTGATE_PERSONAL_KEY })
const { tools, execute } = (await me.connect()).toolkit(ToolFormat.OpenAIResponses) // your MCP tools
const llm = await me.llm() // your models: new OpenAI({ baseURL: llm.baseUrl, apiKey: llm.apiKey })new TrustGate({ apiKey }) 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:
const user = await TrustGate.login({ url: 'https://acme.mcp.neuraltrust.ai/store/mcp' })
const me = await user.connect()
for (const server of me.needsConnect) console.log(`Connect ${server}:`, (await me.connectLink(server))?.connectUrl)
const { tools, execute } = me.toolkit(ToolFormat.OpenAIResponses)The first run opens the browser; the session is kept in
~/.trustgate/sessions.json (owner-only, the same file the Python SDK uses) and
renewed until the sign-in ends, a day on NeuralTrust's cloud. Then
LoginRequiredError says to sign in again. cache: new MemoryTokenCache()
keeps nothing on disk, force: true signs in again regardless, and a backend
that already holds a token uses new TrustGateUser({ url, accessToken }).
Signing in through the browser needs Node; a token you hold works wherever
fetch does.
const { tools, execute } = agent.toolkit<
OpenAI.Responses.Tool,
OpenAI.Responses.ResponseInputItem
>(ToolFormat.OpenAIResponses)toolkit<Tool, Output>() names the two types the provider cares about: what
tools is, and what execute() hands back to it. Both default to unknown,
so naming them is what lets tools go straight into openai.responses.create
without a cast. The SDK depends on no provider package — the types come from
yours.
tools and execute are safe to destructure; the executor stays bound to the
format it was made with.
const { tools, warnings } = agent.toolkit(ToolFormat.OpenAIResponses, { strict: true })Strict buys a guarantee — the model cannot invent an argument — by closing
every object, naming every property as required, and letting the optional ones
accept null. Some schemas cannot be said that way (arbitrary keys, allOf,
prefixItems, an unresolvable $ref); those are emitted unchanged and listed
in warnings, because a tool the model calls imperfectly beats one it cannot
call.
execute() undoes the rewrite before the call reaches the gateway: the nulls
strict asked for are stripped unless the tool's own schema accepts them.
| 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 connectUrl, 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, or no A2A consumer for agents() |
AuthenticationError, RateLimitedError, ServiceUnavailableError, TrustGateServerError |
as named |
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 Python: trustgate-sdk on PyPI. Source,
examples and issues: github.com/NeuralTrust/trustgate-sdk.
npm ci
npm run typecheck
npm test
npm run buildCONTRIBUTING.md has every check CI runs.