MCP Integration

Modei's MCP server exposes 48 tools to Claude Desktop, Cursor, and any MCP-compatible client.

··

What MCP Integration Enables

Modei's MCP server exposes 48 tools to Claude Desktop, Cursor, and any MCP-compatible client. The agent can:

Issue and manage passports for itself or sub-agents
Create and configure gates with guardrails
Verify incoming agent passports before accepting work
Read and export its own audit trail
Apply pre-built templates to gates
Monitor OS Gate sessions

Quick Start

The MCP server is a TypeScript/Node.js package published on npm. Run it directly with npx (requires Node.js 18+):

bash

npx modei-mcp

This interactive CLI walks you through configuring the MCP server for your client. Or configure manually:

Claude Desktop, claude_desktop_config.json

{
  "mcpServers": {
    "modei": {
      "command": "npx",
      "args": ["modei-mcp"],
      "env": {
        "MODEI_API_KEY": "mod_live_xxxxxxxx"
      }
    }
  }
}

After saving, restart Claude Desktop. You'll see an indicator showing the Modei MCP server is connected.

Available Tools (48)

Passports

create_passportget_passportlist_passportsrevoke_passportverify_passportreissue_passport

Gates

create_gateget_gatelist_gatesupdate_gatedelete_gatecheck_gate

Attestations

get_attestationsverify_attestationrecord_attestationget_enforcement_attestationsget_enforcement_attestationverify_enforcement_attestation

Issuers

list_issuers

Enforcement & Constraints

enforce_actionset_constraintsget_constraintslist_constraint_typesget_cumulative_statereset_cumulative_state

Templates

list_constraint_templatesapply_constraint_templatecreate_constraint_template

Commerce

publish_catalogcreate_catalogget_catalogget_catalog_versionget_catalog_impactlist_catalog_versionsdiscover_servicesissue_consumption_attestationgenerate_settlementget_settlementupdate_settlement_statusget_billing_summaryget_sla_compliance

Anonymous Access

set_anonymous_policyget_anonymous_policyget_anonymous_log

Dry Run

authorize_dry_run

API Keys

list_api_keyscreate_api_keyrevoke_api_key

Environment Variables

Variable	Required	Description
MODEI_API_KEY	Yes	Your platform API key (format: mod_live_... or mod_test_...)
MODEI_API_URL	No	Override API base URL (default: https://modei.ai)

OAuth (an industry-standard authorization protocol) 2.0 PKCE (Headless Agents)

The MCP server supports OAuth 2.0 with PKCE, no client secrets needed. This is designed for public clients (agents, CLIs, mobile apps) that cannot securely hold a client secret.

For headless agents (no browser), use the API key method above. For interactive agents that can open a browser, the PKCE flow provides a consent-based authorization:

python

import secrets, hashlib, base64
import httpx

MCP_OAUTH_BASE = "https://modei.ai/api/mcp/oauth"
MCP_CLIENT_ID = "modei-mcp-public"
REDIRECT_URI = "http://localhost:8765/callback"

def generate_pkce_pair():
    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b'=').decode()
    challenge = base64.urlsafe_b64encode(
        hashlib.sha256(verifier.encode()).digest()
    ).rstrip(b'=').decode()
    return verifier, challenge

async def get_access_token(scopes: list[str]) -> str:
    verifier, challenge = generate_pkce_pair()
    state = secrets.token_urlsafe(16)
    
    auth_url = (
        f"{MCP_OAUTH_BASE}/authorize"
        f"?client_id={MCP_CLIENT_ID}"
        f"&redirect_uri={REDIRECT_URI}"
        f"&response_type=code"
        f"&scope={'%20'.join(scopes)}"
        f"&state={state}"
        f"&code_challenge={challenge}"
        f"&code_challenge_method=S256"
    )
    
    print(f"Open this URL:\n{auth_url}")
    auth_code = input("Enter authorization code: ")
    
    async with httpx.AsyncClient() as client:
        r = await client.post(f"{MCP_OAUTH_BASE}/token", data={
            "grant_type": "authorization_code",
            "client_id": MCP_CLIENT_ID,
            "code": auth_code,
            "redirect_uri": REDIRECT_URI,
            "code_verifier": verifier,
        })
        r.raise_for_status()
        return r.json()["access_token"]

Using with TypeScript MCP Client

typescript

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

const client = new Client({ name: 'modei-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
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 to secrets manager immediately!

await client.close();

Agent Autonomy Guide, Path C: full MCP/OAuth PKCE flow.
Python SDK, REST API client for Python.
REST API Reference

Anti-Bait-and-Switch TypeScript SDK