Modei
PricingDocsBlog

Documentation

Theme
Log inSign up

TypeScript SDK & API

Three ways to integrate Modei from TypeScript: the modei-typescript SDK for local cryptographic operations, the modei-mcp package for MCP clients, or direct REST API calls with fetch.

··

modei-typescript (SDK)

The modei-typescript package is the official TypeScript SDK for Modei. It provides local key generation, self-issued passports, and offline signature verification, no network required for crypto operations.

bash
npm install modei-typescript@next

Requires Node.js 18+. Self-issue a passport with a locally generated keypair:

self-issue.ts
// npm install modei-typescript@next
import { AgentCredentials, PassportIssuer } from 'modei-typescript';

const credentials = AgentCredentials.generate();

const passport = new PassportIssuer(credentials, {
  identityClaim: 'research-agent@research.local',
}).selfIssue({
  permissions: [{ permission_key: 'web:read', constraints: {} }],
  expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
});

console.log('passport_id:', passport.envelope.passport_id);

Verify a passport offline:

verify.ts
// npm install modei-typescript@next
import { PassportVerifier } from 'modei-typescript';

const verifier = new PassportVerifier();
const result = verifier.verify(passport.envelope, passport.signature);

if (result.valid) {
  console.log('tier:', result.tier); // "L0" for self-issued
}

modei-mcp (MCP Package)

The modei-mcp package is the official MCP server for Modei. Run it directly with npx or install it globally.

bash
npx modei-mcp
# or install globally
npm install -g modei-mcp

Requires Node.js 18+.

Claude Desktop, claude_desktop_config.json
{
  "mcpServers": {
    "modei": {
      "command": "npx",
      "args": ["modei-mcp"],
      "env": {
        "MODEI_API_KEY": "mod_live_xxxxxxxx"
      }
    }
  }
}

After saving, restart your MCP client. The 48 Modei tools will be available immediately. See MCP Integration for the full tool list.

REST API with fetch

Call the Modei REST API directly from any TypeScript/JavaScript environment. No package required.

typescript
const MODEI_API = "https://modei.ai/api/v1";
const API_KEY = process.env.MODEI_API_KEY!;

async function modei(path: string, options: RequestInit = {}) {
  const res = await fetch(`${MODEI_API}${path}`, {
    ...options,
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(`Modei API error: ${res.status}`);
  return res.json();
}

Create a Passport

typescript
const passport = await modei("/passports", {
  method: "POST",
  body: JSON.stringify({
    agentId: "research-bot-001",
    agentName: "Research Bot",
    permissions: ["web:search", "web:fetch"],
    expiresInDays: 30,
  }),
});

console.log("Passport ID:", passport.passportId);
// Save passport.privateKey to a secrets manager immediately!

Create a Gate

typescript
const gate = await modei("/gates", {
  method: "POST",
  body: JSON.stringify({
    name: "Production API Gate",
    constraints: {
      rateLimits: {
        requestsPerMinute: 60,
        requestsPerDay: 10000,
      },
      spendLimits: {
        dailyUsd: 100.0,
        perTransactionUsd: 10.0,
      },
      allowedDomains: ["api.example.com"],
    },
  }),
});

console.log("Gate ID:", gate.gateId);

Check a Gate

typescript
const result = await modei(`/gates/${gate.gateId}/check`, {
  method: "POST",
  body: JSON.stringify({
    passportId: passport.passportId,
    action: "web:search",
    metadata: { query: "AI agent trust protocols" },
  }),
});

console.log("Decision:", result.decision);        // allow or block
console.log("Attestation:", result.attestationId); // Audit receipt

List Attestations (Audit Trail)

typescript
const attestations = await modei(
  "/attestations?agentId=research-bot-001&limit=50"
);

for (const att of attestations.items) {
  console.log(
    `  ${att.decision.toUpperCase().padEnd(6)}  ${att.timestamp}  ${att.request?.action ?? "unknown"}`
  );
}

console.log(`\nTotal: ${attestations.total} attestations`);

Revoke a Passport

typescript
await modei(`/passports/${passport.passportId}/revoke`, {
  method: "POST",
  body: JSON.stringify({ reason: "Agent retired" }),
});

Using with MCP Client SDK

If you're building a custom MCP client, you can connect to the Modei MCP server programmatically:

typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "my-agent", version: "1.0.0" });

const transport = new StreamableHTTPClientTransport(
  new URL("https://modei.ai/api/mcp"),
  { headers: { Authorization: `Bearer ${process.env.MODEI_API_KEY}` } }
);

await client.connect(transport);

// Issue a passport via MCP tool call
const result = await client.callTool({
  name: "issue_passport",
  arguments: {
    agent_id: "typescript-agent-001",
    agent_name: "TypeScript Demo Agent",
    permissions: ["web:search", "documents:read"],
    expires_in_days: 30,
  },
});

const passport = JSON.parse(result.content[0].text);
console.log("Passport ID:", passport.passportId);
// Save passport.privateKey immediately!

await client.close();

Related

MCP IntegrationPython SDK