Metorial: an identity and access layer for AI agents that talk to 1200+ integrations

The gap Metorial is aimed at: agents with borrowed credentials

The README opens with a blunt diagnosis: agents are being connected to production systems, and there is no consistent identity and access layer around them. In practice that means an agent inherits a long-lived API key, acts as whoever configured it, and leaves no record separating its actions from a human's. Metorial's answer is to become a control plane that sits between agents and integrations, so auth, permissions and observability are handled in one place rather than re-implemented per app.

The audience is narrow and specific. It is platform and security engineers at companies where agents already touch Slack, GitHub, Google Calendar or SAP, and where someone has to answer the question of which agent acted with whose credentials. A solo developer wiring one API key into a script is not the target reader, and the README does not pretend otherwise.

How the control plane is structured: deployments, sessions, adapters

The mechanism visible in the README is a three-step chain. You create a provider deployment, which names a provider such as metorial-search and returns an id. You then call connect with an adapter and a list of provider deployments, which returns a session. That session exposes tools() in the shape your agent framework expects.

The adapter is the seam. The README shows metorialAiSdk() for the Vercel AI SDK and metorial_pydantic_ai() for Pydantic AI, and the SDKs listed are JavaScript/TypeScript and Python. Tool exposure happens through the session, so the agent framework never sees raw credentials; it sees a tool list. Auth flows are separate: for services needing user authentication, a setup session returns a URL the user visits, and the resulting auth config is reused afterwards. That is the OAuth path for Slack, GitHub, Google Calendar or SAP.

The repository itself is a monorepo. Top-level entries include integrations/, adapters/, packages/, scripts/ and test-integrations/, with Bun workspaces and Turbo builds. The root package.json is named @metorial/integrations-root and its scripts are about building and validating integration packages, not about running the control plane. The README points self-hosting at a separate repository, metorial-platform, which it calls the engine behind Metorial and the code that powers it.

Installing the SDK and making a first MCP-backed call

The README's quick start uses Metorial Search, a built-in web search provider that needs no auth configuration, which makes it the cheapest way to confirm the wiring works. Install the JavaScript packages first.

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

You will need a METORIAL_API_KEY in the environment. The README does not document how to obtain one for a self-hosted instance; the hosted platform is where the README sends readers for setup. The script below creates a provider deployment named Metorial Search, opens a session through the AI SDK adapter, and passes the session tools to streamText. The stopWhen: stepCountIs(10) line caps the agent at ten steps, which matters because a search tool can loop.

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

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

let deployment = await metorial.providerDeployments.create({
  name: 'Metorial Search',
  providerId: 'metorial-search'
});

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

With the session in hand, run the model and stream the output. The tools() call is what connects the model to the integration.

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()
});

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

You should see streamed text containing a summary of search results. If the key is missing or the provider id is wrong, the failure surfaces at deployment creation or connect, before the model runs. The Python path installs as pip install metorial pydantic-ai python-dotenv and follows the same create-connect-run shape with metorial_pydantic_ai().

OAuth setup sessions and the magic URL pattern

For anything requiring a user to log in, the README describes setup sessions. You create one with a providerId and a providerAuthMethodId, and it returns a url. The README prints that URL with the label Authenticate here and then waits for completion. The resulting auth config is reused, which is the part that saves work: the OAuth handshake happens once and the agent session references it afterwards.

This is also where the design gets opinionated in a way worth flagging. The README calls it a single magic URL. That is convenient, but it means the trust boundary runs through whoever holds that URL during the setup window, and the README does not describe expiry, single-use enforcement, or what happens if the setup session is abandoned. The security section lists centralized access control, scoped credentials and audit logs, but the setup-session lifecycle is not spelled out. If that window matters to your threat model, treat it as something to confirm against the API documentation at metorial.com/api rather than something the README answers.

Where Metorial is the wrong tool

The repository you are reading is the integration catalog, not the engine. The README states plainly that metorial-platform is the code that powers the engine and is the self-hostable piece. So if your goal is to run Metorial on your own infrastructure, this repository alone is not sufficient, and the README does not document a single-repo self-host path. It also does not document rollback, version pinning for integrations, or migration between releases; there are no retrieved releases to point at.

The second boundary is scale of need. The core value is shared access patterns across teams and projects. If one service calls one API with one key, you are paying for a control plane to solve a problem you do not have. The third boundary is licence clarity. The repository's licence identifier is NOASSERTION, and the README does not discuss terms. That is not a reason to avoid the project, but it is a reason to read the LICENSE file before it reaches production.

How it differs from raw MCP servers and from a hosted aggregator

The obvious comparison is running MCP servers yourself. In that approach each server holds its own credentials, and access control is whatever you build around the process. Metorial inserts a layer: the agent gets a session with tools, and the credential and permission model lives in the control plane. The trade is one more service in the path, and a provider deployment object to manage per integration.

The second comparison is a hosted integration aggregator. Metorial offers that too: the README recommends the hosted platform as the fastest way to get started and links to platform.metorial.com. The difference is that the platform repository is open source and self-hostable, so the hosted route is a convenience rather than the only option. That matters if your security posture forbids third-party credential custody. It also means the hosted and self-hosted paths can diverge in what is available, which the README does not clarify.

Maintenance signals and what the repository tells you

The last push to this repository was on 2026-09-10, and the repository is not archived. The toolchain is current and specific: Bun 1.4.0 as the package manager, Node >=18, TypeScript 5.8.2, Turbo 2.5.5 and Biome 2.4.15 in devDependencies. The root scripts include integrations:validate-pr and packages:sync-versions, which suggests contributions are expected to keep integration packages consistent rather than accumulate drift.

The licence identifier is NOASSERTION, which means GitHub could not map the LICENSE file to a known template. The README does not state terms, and nothing in the repository description describes commercial restrictions or obligations. Read the LICENSE file directly; this is a fact about the repository, not legal advice. On upgrade cost, one concrete observation holds: integrations are separate workspace packages under integrations/, and the root has a script to sync package versions, so an upgrade is not a single version bump across the tree.

Editorial conclusion

Adopt Metorial if you already run agents against production SaaS systems and need one place to hold credentials, scope them per agent, and log who did what. Do not adopt it as a general integration library for a single script that calls one API with one static key; the control-plane layer adds a deployment and a provider model you will not use. Before committing, verify three things: whether the NOASSERTION licence identifier on this repository resolves to terms your legal team accepts, whether metorial-platform self-hosting covers the integrations you need, and whether the audit log fields match the identity model your security team already runs.

Frequently asked questions

Official sources

1. Issues
2. metorial/metorial on GitHub
3. Project website
4. README