Custom JavaScript SDK Quickstart

Enterprise agents, scoped to your org, governed by your policies.

Use this quickstart when your agent runtime is not an MCP-native desktop client: LangChain.js, an in-house orchestrator, a custom RAG service, or direct MCP-over-HTTP wiring. The example mints an OIDC token, sends Authorization: Bearer <token> with x-faos-tenant-id, and invokes one tenant-scoped FAOS tool.

Back to Works Everywhere.

Step 1: Install

cd docs-site/examples/custom/js-sdk
pnpm install --frozen-lockfile
cp .env.example .env

Fill in .env with the service-account credentials issued for the target tenant.

FAOS_BASE_URL=https://api.staging.faosx.ai
FAOS_CLIENT_ID=your-client-id
FAOS_CLIENT_SECRET=your-client-secret
FAOS_TENANT_ID=your-tenant-id

Step 2: Auth

The example uses the OAuth 2.0 client-credentials flow. FAOS_TENANT_ID is mandatory; it is sent as x-faos-tenant-id beside the bearer token so auth and tenant routing stay aligned.

const tokenResponse = await fetch(`${config.baseUrl}/oauth/token`, {
  method: 'POST',
  headers: {
    'content-type': 'application/x-www-form-urlencoded',
    'x-faos-tenant-id': config.tenantId,
  },
  body: new URLSearchParams({
    grant_type: 'client_credentials',
    client_id: config.clientId,
    client_secret: config.clientSecret,
    audience: 'faos-mcp',
  }),
});

Step 3: Invoke

Run the included minimal TypeScript example:

pnpm run start

The tool call sends both headers on every request:

const headers = {
  authorization: `Bearer ${accessToken}`,
  'content-type': 'application/json',
  'x-faos-tenant-id': config.tenantId,
};

The runnable package lives at docs-site/examples/custom/js-sdk.

Troubleshooting

Auth failures

401 usually means the OIDC token mint failed or the token audience is not faos-mcp. 403 usually means the token is valid but not authorized for the requested tool or tenant. Confirm the request includes both Authorization: Bearer <token> and x-faos-tenant-id; omitting the tenant header is the most common cause of a wrong tenant response or a cross-tenant leak concern.

CORS

This quickstart is for Node.js server-side execution. If you run the same call from a browser, configure the FAOS MCP gateway CORS allowlist for your origin and keep client secrets out of browser bundles. Browser requests still need Authorization: Bearer and x-faos-tenant-id.

Rate limits

429 responses include a retry hint in retry-after when the gateway can provide one. Back off per tenant and per tool instead of retrying globally, otherwise one busy workflow can starve unrelated tenant traffic.

Production Notes

Pin SDK dependencies by major and minor, rotate service-account secrets through your tenant admin workflow, and keep FAOS_TENANT_ID explicit in each environment. Cross-tenant leakage is almost always a configuration bug: tenant A credentials, tenant B header, or a shared process reusing headers between requests.