Metorial Node.js SDK

The official Node.js/TypeScript SDK for Metorial - The open source integration platform for agentic AI

Complete API Documentation

API Documentation - Complete API reference and guides

Multi-Provider Support

Use the same tools across different AI providers

| Provider | Model Examples | Client Required |
| ---------- | ------------------------------------------------------------------------------- | ------------------ |
| OpenAI | gpt-4o, gpt-4, gpt-3.5-turbo | openaiClient |
| Anthropic | claude-3-5-sonnet-20241022, claude-3-haiku-20240307 | anthropicClient |
| Google | gemini-pro, gemini-1.5-pro, gemini-flash | googleClient |
| DeepSeek | deepseek-chat, deepseek-coder | deepseekClient |
| Mistral | mistral-large-latest, mistral-small-latest | mistralClient |
| XAI | grok-beta, grok-vision-beta | xaiClient |
| TogetherAI | meta-llama/Llama-2-70b-chat-hf, NousResearch/Nous-Hermes-2-Mixtral-8x7B-DPO | togetheraiClient |

Quick Start

The simplest way to get started is with the .run() method, which handles session management and conversation loops automatically:

``typescript
import { Metorial } from 'metorial';
import OpenAI from 'openai';

let metorial = new Metorial({ apiKey: 'your-metorial-api-key' });
let openai = new OpenAI({ apiKey: 'your-openai-api-key' });

let result = await metorial.run({
message: 'Scan my slack messages for meetings and put them on my google calendar.',
serverDeployments: ['google-calendar-server', 'slack-server'],
model: 'gpt-4o',
client: openai,
maxSteps: 10 // Optional: limit conversation steps
});

console.log(Response (completed in ${result.steps} steps):);
console.log(result.text);
`

$3

`typescript
// With tool filtering and provider-specific options
let result = await metorial.run({
message: 'Analyze this codebase and create a summary',
serverDeployments: ['deployment-1', 'deployment-2'],
model: 'claude-3-5-sonnet-20241022',
client: anthropic,
maxSteps: 15,

tools: ['github-search', 'file-reader'], // Optional: limit to specific tools

// Provider specific options
temperature: 0.7,
max_tokens: 2000
});
`

OAuth Integration

When working with services that require user authentication (like Google Calendar, Slack, etc.), Metorial provides OAuth session management to handle the authentication flow:

`typescript
import { Metorial } from 'metorial';
import Anthropic from '@anthropic-ai/sdk';

let metorial = new Metorial({ apiKey: 'your-metorial-api-key' });
let anthropic = new Anthropic({ apiKey: 'your-anthropic-api-key' });

// Create OAuth sessions for services that require user authentication
let [googleCalOAuthSession, slackOAuthSession] = await Promise.all([
metorial.oauth.sessions.create({
serverDeploymentId: 'your-google-calendar-server-deployment-id'
}),
metorial.oauth.sessions.create({
serverDeploymentId: 'your-slack-server-deployment-id'
})
]);

// Give user OAuth URLs for authentication
console.log('OAuth URLs for user authentication:');
console.log( Google Calendar: ${googleCalOAuthSession.url});
console.log( Slack: ${slackOAuthSession.url});

// Wait for user to complete OAuth flow
await metorial.oauth.waitForCompletion([googleCalOAuthSession, slackOAuthSession]);

console.log('OAuth sessions completed!');

// Now use the authenticated sessions in your run
let result = await metorial.run({
message: Look in Slack for mentions of potential partners. Use Exa to research their background,
company, and email. Schedule a 30-minute intro call with them for an open slot on Dec 13th, 2025
SF time and send me the calendar link. Proceed without asking for any confirmations.,

serverDeployments: [
{
serverDeploymentId: 'your-google-calendar-server-deployment-id',
oauthSessionId: googleCalOAuthSession.id
},
{
serverDeploymentId: 'your-slack-server-deployment-id',
oauthSessionId: slackOAuthSession.id
},
{
serverDeploymentId: 'your-exa-server-deployment-id' // No OAuth needed for Exa
}
],
client: anthropic,
model: 'claude-3-5-sonnet-20241022'
});

console.log(result.text);
`

$3

1. Create OAuth Sessions: Call metorial.oauth.sessions.create() for each service requiring user authentication
2. Send URLs: Show the OAuth URLs to users so they can authenticate in their browser
3. Wait for Completion: Use metorial.oauth.waitForCompletion() to wait for users to complete the OAuth flow
4. Use Authenticated Sessions: Pass the oauthSessionId when configuring serverDeployments

Examples

Check out the examples/ directory for more comprehensive examples:

- examples/typescript-openai-run/ - Simple .run() method example
- examples/typescript-openai/ - Manual OpenAI integration
- examples/typescript-anthropic/ - Anthropic integration
- examples/typescript-ai-sdk/ - AI SDK integration

Installation

`bash
npm install metorial


or

yarn add metorial

or

pnpm add metorial

or

bun add metorial
`

Manual Integration (More Control)

$3

`typescript
import { Metorial } from 'metorial';
import { metorialOpenAI } from '@metorial/openai';
import OpenAI from 'openai';

let main = async () => {
// Initialize clients
let metorial = new Metorial({
apiKey: 'your-metorial-api-key'
});

let openai = new OpenAI({ apiKey: 'your-openai-api-key' });

// Use Metorial tools with OpenAI
await metorial.withProviderSession(
metorialOpenAI.chatCompletions,
{ serverDeployments: ['your-server-deployment-id'] },
async session => {
let messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
{ role: 'user', content: 'What are the latest commits?' }
];

for (let i = 0; i < 10; i++) {
// Call OpenAI with Metorial tools
let response = await openai.chat.completions.create({
model: 'gpt-4o',
messages,
tools: session.tools
});

let choice = response.choices[0]!;
let toolCalls = choice.message.tool_calls;

if (!toolCalls) {
console.log(choice.message.content);
return;
}

// Execute tools through Metorial
let toolResponses = await session.callTools(toolCalls);

// Add to conversation
messages.push(
{
role: 'assistant',
tool_calls: choice.message.tool_calls
},
...toolResponses
);
}
}
);
};

main();
`

Provider Examples

$3

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

let metorial = new Metorial({
apiKey: 'your-metorial-api-key'
});

let anthropic = new Anthropic({
apiKey: 'your-anthropic-api-key'
});

await metorial.withProviderSession(
metorialAnthropic,
{ serverDeployments: ['your-server-deployment-id'] },
async session => {
let messages: Anthropic.Messages.MessageParam[] = [
{ role: 'user', content: 'Help me with this GitHub task: ...' }
];

// Dedupe tools by name
let uniqueTools = Array.from(new Map(session.tools.map(t => [t.name, t])).values());

let response = await anthropic.messages.create({
model: 'claude-3-5-sonnet-20241022',
max_tokens: 1024,
messages,
tools: uniqueTools
});

// Handle tool calls
let toolCalls = response.content.filter(
(c): c is Anthropic.Messages.ToolUseBlock => c.type === 'tool_use'
);

if (toolCalls.length > 0) {
let toolResponses = await session.callTools(toolCalls);
messages.push({ role: 'assistant', content: response.content as any }, toolResponses);
}
}
);
`

$3

`typescript
import { Metorial } from 'metorial';
import { metorialGoogle } from '@metorial/google';
import { GoogleGenerativeAI } from '@google/generative-ai';

let metorial = new Metorial({
apiKey: 'your-metorial-api-key'
});

let genAI = new GoogleGenerativeAI('your-google-api-key');

await metorial.withProviderSession(
metorialGoogle,
{ serverDeployments: ['your-server-deployment-id'] },
async session => {
let model = genAI.getGenerativeModel({
model: 'gemini-pro',
tools: session.tools
});

let response = await model.generateContent('What can you help me with?');

// Handle function calls if present
// ... tool call handling logic
}
);
`

$3

`typescript
import { Metorial } from 'metorial';
import { metorialDeepSeek } from '@metorial/deepseek';
import OpenAI from 'openai';

// Works with any OpenAI-compatible API
let deepseekClient = new OpenAI({
apiKey: 'your-deepseek-key',
baseURL: 'https://api.deepseek.com'
});

let metorial = new Metorial({
apiKey: 'your-metorial-api-key'
});

await metorial.withProviderSession(
metorialDeepSeek.chatCompletions,
{ serverDeployments: ['your-server-deployment-id'] },
async session => {
let response = await deepseekClient.chat.completions.create({
model: 'deepseek-chat',
messages: [{ role: 'user', content: 'Help me code' }],
tools: session.tools
});
// ... handle response
}
);
`

Available Providers

| Provider | Import | Format | Description |
| ---------- | ---------------------- | ---------------------------- | ----------------------------- |
| OpenAI | @metorial/openai | OpenAI function calling | GPT-4, GPT-3.5, etc. |
| Anthropic | @metorial/anthropic | Claude tool format | Claude 3.5, Claude 3, etc. |
| Google | @metorial/google | Gemini function declarations | Gemini Pro, Gemini Flash |
| Mistral | @metorial/mistral | Mistral function calling | Mistral Large, Codestral |
| DeepSeek | @metorial/deepseek | OpenAI-compatible | DeepSeek Chat, DeepSeek Coder |
| TogetherAI | @metorial/togetherai | OpenAI-compatible | Llama, Mixtral, etc. |
| XAI | @metorial/xai | OpenAI-compatible | Grok models |
| AI SDK | @metorial/ai-sdk | Framework tools | Vercel AI SDK, etc. |

Core API

$3

`typescript
import { Metorial } from 'metorial';

let metorial = new Metorial({
apiKey: 'your-api-key'
});
`

$3

`typescript
// Provider session (recommended)
await metorial.withProviderSession(
provider.chatCompletions,
{ serverDeployments: ['deployment-id'] },
async session => {
// Your session logic here
}
);

// Direct session management
await metorial.withSession(['deployment-id'], async session => {
// Your session logic here
});
`

$3

The session object passed to your callback provides:

`typescript
interface Session {
// Tool definitions formatted for your provider
tools: any[];

// Execute tools and get responses
callTools(toolCalls: any[]): Promise;

// Advanced access
toolManager: MetorialMcpToolManager; // Direct tool management
session: MetorialMcpSession; // Raw MCP session
}
`

Error Handling

`typescript
import { MetorialAPIError } from 'metorial';

try {
await metorial.withProviderSession(/ ... /);
} 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