Agent Envelope MCP server

agent-envelope-mcp

agent-envelope-mcp is the MCP adapter for AgentEnvelope.

Any MCP-capable runtime can check delegated authority before it acts: OpenAI Agents SDK, OpenAI Responses remote MCP, Claude Desktop, Cursor, LangChain, LangGraph, CrewAI, or a custom runtime.

Prompts can request actions; AgentEnvelope decides whether the actor has authority to perform them.

Choose Your Mode

Local stdio:

npx -y agent-envelope-mcp

Streamable HTTP:

npx -y agent-envelope-mcp --http --port 8787

The HTTP endpoint is:

http://127.0.0.1:8787/mcp

Health check:

http://127.0.0.1:8787/health

No API key is needed to start the server or to use sovereign signature/record verification. Hosted-governance tools require AEAPIKEY or, in HTTP mode, an Authorization: Bearer header.

For verification-only deployments, set AETOOLS=readonly. In that mode the server does not register aemint, so MCP clients can only call sovereign verification and hosted read/query tools.

Tools

Most tools return both readable MCP content and machine-readable structuredContent.

Runtime Rule

Call AgentEnvelope before the real action. Execute only if allowed === true.

const decision = await authorizeAction(input);

if (decision.allowed !== true) {
  throw new Error(decision.message || decision.reason);
}

await executeRealTool(input);

Do not pass AEMINTMATERIAL, vault roots, seeds, or private domain material to the model or MCP client. Keep those in the bot runtime secret store.

Local MCP Config

{
  "mcpServers": {
    "agent-envelope": {
      "command": "npx",
      "args": ["-y", "agent-envelope-mcp"],
      "env": {
        "AE_API_KEY": "your-portal-issued-api-key"
      }
    }
  }
}

OpenAI Agents SDK

import { Agent, MCPServerStdio, run } from "@openai/agents";

const ae = new MCPServerStdio({
  name: "agent-envelope",
  fullCommand: "npx -y agent-envelope-mcp",
  env: {
    AE_API_KEY: process.env.AE_API_KEY
  }
});

await ae.connect();

const agent = new Agent({
  name: "Support Agent",
  instructions:
    "Before executing any real action, verify authority with AgentEnvelope MCP. Treat failed verification as a hard denial.",
  mcpServers: [ae]
});

const result = await run(agent, "Can I issue a refund on order ORD-123?");
console.log(result.finalOutput);

await ae.close();

OpenAI Responses Remote MCP

Use Streamable HTTP mode locally, or point OpenAI at your deployed MCP URL after the web/API edge is configured to serve the MCP HTTP endpoint:

Shortened. The full README is on GitHub.