Metorial Node.js SDK

The official Node.js/TypeScript SDK for Metorial. Give your AI agents access to tools like Slack, GitHub, SAP, and hundreds more through MCP — without managing servers, auth flows, or infrastructure.

Sign up for a free account to get started.

Complete API Documentation

• Documentation - Documentation and guides
• API Reference - Complete API reference

Installation

npm install metorial
# or
yarn add metorial
# or
pnpm add metorial
# or
bun add metorial

Supported LLM Integrations

This SDK provides adapter packages that format MCP tools for each LLM. You can also use the API directly.

Quick Start

This example uses Metorial Search, a built-in web search provider that requires no auth configuration. You just need two environment variables:

• METORIAL_API_KEY from platform.metorial.com
• ANTHROPIC_API_KEY from console.anthropic.com

npm install metorial @metorial/ai-sdk @ai-sdk/anthropic ai

import { anthropic } from '@ai-sdk/anthropic';
import { metorialAiSdk } from '@metorial/ai-sdk';
import { Metorial } from 'metorial';
import { stepCountIs, streamText } from 'ai';

let metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY! });

// Create a deployment for Metorial Search (built-in web search, no auth needed)
let deployment = await metorial.providerDeployments.create({
  name: 'Metorial Search',
  providerId: 'metorial-search'
});

let session = await metorial.connect({
  adapter: metorialAiSdk(),
  providers: [{ providerDeploymentId: deployment.id }]
});

let result = streamText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt:
    'Search the web for the latest news about AI agents and summarize the top 3 stories.',
  stopWhen: stepCountIs(10),
  tools: session.tools(),
  onStepFinish: step => {
    if (step.toolCalls?.length) {
      console.log(step.toolCalls.map(tc => tc.toolName).join(', '));
    }
  }
});

for await (let part of result.textStream) {
  process.stdout.write(part);
}

See the full runnable example at examples/typescript-quick-start/.

Authenticating MCP Tool Providers

The Quick Start above used Metorial Search, which requires no authentication. Most providers — Slack, GitHub, SAP, and others — require credentials. Here are the options, from simplest to most flexible.

Key concepts:

• Provider — an MCP tool integration (e.g. Slack, GitHub, Metorial Search). Browse available providers at platform.metorial.com.
• Provider Deployment — an instance of a provider configured for your project. You can create deployments in the dashboard or programmatically.
• Auth Credentials — your OAuth app registration (client ID, client secret, scopes).
• Auth Config — an already-authenticated connection with a token, service account, or specific user via an OAuth flow.

Dashboard-Configured Deployments

Some providers (Exa, Tavily) use API keys configured entirely in the dashboard. Just pass the deployment ID — no auth code needed:

providers: [{ providerDeploymentId: 'your-exa-deployment-id' }];

Pre-Created Auth Config

An auth config represents an already-authenticated connection to a provider — for example, a user who has completed the OAuth flow for Slack. Once created (via the dashboard or a setup session), reference it by ID:

providers: [
  {
    providerDeploymentId: 'your-slack-deployment-id',
    providerAuthConfigId: 'your-auth-config-id'
  }
];

Inline Credentials

Pass credentials directly without pre-creating them in the dashboard:

providers: [
  {
    providerDeploymentId: 'your-deployment-id',
    providerAuthConfig: {
      providerAuthMethodId: 'your-auth-method-id',
      credentials: { access_token: 'user-access-token' }
    }
  }
];

OAuth Flow

For services like Slack or GitHub where each end-user authenticates individually, use setup sessions to handle the OAuth flow:

import { metorialAiSdk } from '@metorial/ai-sdk';
import { Metorial } from 'metorial';

let metorial = new Metorial({ apiKey: process.env.METORIAL_API_KEY! });

// 1. Create a setup session for the provider
let setupSession = await metorial.providerDeployments.setupSessions.create({
  providerId: 'your-slack-provider-id',
  providerAuthMethodId: 'your-slack-auth-method-id'
  // callbackUri: 'https://yourapp.com/oauth/callback'
});

// 2. Send the OAuth URL to your user
console.log(`Authenticate here: ${setupSession.url}`);

// 3. Wait for the user to complete OAuth
let completed = await metorial.providerDeployments.setupSessions.waitForCompletion([
  setupSession
]);

// 4. Use the auth config in a connected session
let session = await metorial.connect({
  adapter: metorialAiSdk(),
  providers: [
    {
      providerDeploymentId: 'your-slack-deployment-id',
      providerAuthConfigId: completed[0]!.authConfig!.id
    }
  ]
});

// Pass session.tools() to your model SDK

For a multi-provider OAuth example, see examples/typescript-ai-sdk/.

Multiple Providers in One Session

Combine providers freely in a single session — each can use a different auth method:

providers: [
  { providerDeploymentId: 'your-search-deployment-id' },
  {
    providerDeploymentId: 'your-slack-deployment-id',
    providerAuthConfigId: 'slack-auth-config-id'
  },
  {
    providerDeploymentId: 'your-github-deployment-id',
    providerAuthConfig: {
      providerAuthMethodId: 'github-auth-method-id',
      credentials: { access_token: 'ghp_...' }
    }
  }
];

Session Templates

Pre-configure provider combinations on the dashboard, then reference them by ID. This is useful when you want to manage which providers and auth configs are used without changing code — for example, bundling Metorial Search + GitHub + Slack into a single template that your team can reuse:

let session = await metorial.connect({
  adapter: metorialAiSdk(),
  providers: [{ sessionTemplateId: 'your-template-id' }]
});

// All providers from the template are available via session.tools()

See examples/typescript-provider-config/ for a full example of session templates and other provider configuration patterns.

Enterprise: Bring Your Own (BYO) Credentials

For enterprise deployments, you have flexible options:

• Shared deployment: Deploy once and share with all users (works well for API key-based tools like Exa, Tavily)
• BYO OAuth: For services like SAP, enterprises can register their own OAuth app credentials:

let credentials = await metorial.providerDeployments.authCredentials.create({
  providerId: 'your-sap-provider-id',
  name: 'Our SAP OAuth App',
  config: {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    scopes: ['read', 'write']
  }
});

• Dynamic deployments: Create provider deployments programmatically via the Provider Deployment API:

let deployment = await metorial.providerDeployments.create({
  name: 'Metorial Search',
  providerId: 'metorial-search'
});
// use deployment.id in your session's providers array

Session Options

• Streaming: Pass session.tools() into streaming APIs like AI SDK's streamText(). See the Quick Start for a full example.
• Templates: You can include { sessionTemplateId: '...' } in the providers array to load a dashboard-managed session template.
• Raw MCP access: If you need lower-level MCP session lifecycle control instead of an adapter-backed connect() session, see the lower-level SDK docs.

Examples

Check out the examples/ directory for more comprehensive examples:

• typescript-quick-start - Quick start with Metorial Search
• typescript-ai-sdk - AI SDK + Anthropic (v5/v6)
• typescript-ai-sdk-v4 - AI SDK + Anthropic (v4)
• typescript-anthropic - Anthropic SDK
• typescript-openai - OpenAI
• typescript-openai-compatible - Any OpenAI-compatible API
• typescript-google - Google Gemini
• typescript-deepseek - DeepSeek
• typescript-mistral - Mistral
• typescript-togetherai - TogetherAI
• typescript-xai - xAI (Grok)
• typescript-langchain - LangChain + LangGraph
• typescript-provider-config - Provider configuration patterns

LLM Integration Examples

All LLM integrations follow the same metorial.connect({ adapter, providers }) pattern. See examples/ for complete examples with every supported LLM.

Anthropic (Claude)

import { metorialAnthropic } from '@metorial/anthropic';
import Anthropic from '@anthropic-ai/sdk';

let anthropic = new Anthropic();

let session = await metorial.connect({
  adapter: metorialAnthropic(),
  providers: [{ providerDeploymentId: deployment.id }]
});

let response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 4096,
  messages: [{ role: 'user', content: 'Search for the latest AI news.' }],
  tools: session.tools()
});

let toolCalls = response.content.filter(c => c.type === 'tool_use');
if (toolCalls.length > 0) {
  let toolResponses = await session.callTools(toolCalls);
  // continue the conversation with tool results...
}

OpenAI-Compatible (DeepSeek, TogetherAI, XAI)

import { metorialDeepseek } from '@metorial/deepseek';
import OpenAI from 'openai';

// Works with any OpenAI-compatible API
let client = new OpenAI({
  apiKey: process.env.DEEPSEEK_API_KEY!,
  baseURL: 'https://api.deepseek.com'
});

let session = await metorial.connect({
  adapter: metorialDeepseek(),
  providers: [{ providerDeploymentId: deployment.id }]
});

let response = await client.chat.completions.create({
  model: 'deepseek-chat',
  messages: [{ role: 'user', content: 'Search for the latest AI news.' }],
  tools: session.tools()
});

// ... handle tool_calls from response via session.callTools()

The v1 API is still accessible via metorial.v1.*.

Error Handling

import { metorialAiSdk } from '@metorial/ai-sdk';
import { MetorialAPIError } from 'metorial';

try {
  await metorial.connect({
    adapter: metorialAiSdk(),
    providers: [{ providerDeploymentId: 'your-deployment-id' }]
  });
} catch (error) {
  if (error instanceof MetorialAPIError) {
    console.error(`API Error: ${error.message} (Status: ${error.status})`);
  } else {
    console.error(`Unexpected error:`, error);
  }
}

License

MIT License - see LICENSE file for details.

Support

Documentation · GitHub Issues · Email Support