Skip to content

Latest commit

 

History

History

typescript

README.md

@neuraltrust/trustgate

npm 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/trustgate

Setup

import { TrustGate, ToolFormat } from '@neuraltrust/trustgate'

const tg = new 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 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.

An agent that acts as the application

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 accounts

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

An agent acting for one of its users

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.

Calling the application's A2A agents

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.

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

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.

The provider's types

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.

Strict mode

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.

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

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 Python: trustgate-sdk on PyPI. Source, examples and issues: github.com/NeuralTrust/trustgate-sdk.

Development

npm ci
npm run typecheck
npm test
npm run build

CONTRIBUTING.md has every check CI runs.