AgentsID

Identity, permissions, and audit for AI agents.
The Auth0 for the agent economy.

Docs · Guides · Dashboard · API Reference

The Problem

AI agents are accessing databases, sending emails, calling APIs, and making purchases -- but there is no standard way to identify them, limit what they can do, or trace their actions back to a human.

• 88% of MCP servers need authentication, but only 8.5% use OAuth
• 53% rely on static API keys passed as environment variables
• 80% of organizations cannot tell what their agents are doing in real-time

Auth0 handles humans. AgentsID handles agents.

How It Works

┌─────────────────────────────────────────────────────┐
│  Your App                                           │
│                                                     │
│  ┌───────────┐  ┌───────────┐  ┌────────────────┐  │
│  │ Agent A   │  │ Agent B   │  │ MCP Server     │  │
│  │ (token)   │  │ (token)   │  │ + middleware    │  │
│  └─────┬─────┘  └─────┬─────┘  └───────┬────────┘  │
│        │              │                │            │
└────────┼──────────────┼────────────────┼────────────┘
         │              │                │
         └──────────────┼────────────────┘
                        │
                        ▼
              ┌─────────────────┐
              │   AgentsID API  │
              │                 │
              │  Identity       │  Register, issue tokens
              │  Permissions    │  Per-tool deny-first rules
              │  Delegation     │  Human → Agent → Agent
              │  Audit          │  Tamper-evident hash chain
              └─────────────────┘

Every tool call flows through AgentsID. The middleware validates the agent's token, checks permissions against deny-first rules, and logs the result to a tamper-evident audit chain -- all in under 1ms.

Quick Start

Install

npm install @agentsid/sdk    # TypeScript
pip install agentsid          # Python
gem install agentsid          # Ruby

Register an agent

import { AgentsID } from '@agentsid/sdk';

const aid = new AgentsID({ projectKey: 'aid_proj_...' });

const { agent, token } = await aid.registerAgent({
  name: 'research-bot',
  onBehalfOf: 'user_123',
  permissions: ['search_*', 'save_memory'],
});

Validate every tool call

const result = await aid.validate(token, 'delete_user');

if (!result.allowed) {
  console.log('Blocked:', result.reason);
  // → "Tool 'delete_user' is not in the allow list"
}

Add MCP middleware (2 lines)

import { createHttpMiddleware } from '@agentsid/sdk';

const guard = createHttpMiddleware({ projectKey: 'aid_proj_...' });
// That's it. Every tool call is now validated.

Features

Deny-First Permissions

Every tool call is blocked unless explicitly allowed. Fine-grained rules with wildcards, conditions, schedules, and rate limits.

await aid.setPermissions(agentId, [
  { toolPattern: 'search_*', action: 'allow' },
  { toolPattern: 'deploy_*', action: 'allow',
    schedule: { hoursStart: 9, hoursEnd: 17, timezone: 'US/Pacific' },
    rateLimit: { max: 5, per: 'hour' } },
  { toolPattern: 'delete_*', action: 'allow', requiresApproval: true },
]);

HMAC-SHA256 Tokens

Cryptographically signed agent tokens verified without a database call. Supports key rotation with zero downtime.

Delegation Chains

Every agent action traces back to a human. Multi-hop delegation (Human → Agent A → Agent B) with automatic scope narrowing -- child agents can never have more permissions than their parent.

Tamper-Evident Audit

SHA-256 hash chain links every event. If anyone modifies a record, the chain breaks. Queryable by agent, tool, action, and time range. Exportable for compliance.

Approval Gates

Sensitive actions pause for human approval. Email notifications, webhook triggers, time-boxed decisions.

const pending = await aid.listApprovals();
await aid.approve(approvalId, { decidedBy: 'admin@example.com' });

Webhooks

Real-time event notifications for 8 event types:

agent.created · agent.revoked · agent.denied · limit.approaching · limit.reached · approval.requested · approval.decided · chain.broken

SDKs

CLI

npx agentsid init                           # Create project, get API key
npx agentsid register-agent --name "bot"    # Register an agent
npx agentsid list-agents                    # List all agents
npx agentsid audit --agent <id>             # View audit log
npx agentsid revoke <id>                    # Revoke an agent

GitHub Action

Scan any MCP server for security issues directly from GitHub. The action posts a grade on every PR, writes a full dashboard to the workflow run summary, and uploads findings to the native Security → Code scanning tab as SARIF.

Try it without installing

Open an issue titled scan: <package-or-url> on this repo and the scanner runs automatically. Results are posted as a comment within about 30 seconds.

Example: scan: @playwright/mcp-server

CI Usage

Add this to any workflow to scan your MCP server on every pull request:

name: MCP Security Scan
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write    # post PR comment
      security-events: write  # upload findings to Security tab
    steps:
      - uses: AgentsID-dev/agentsid@master
        with:
          target: 'npx @your-org/your-mcp-server'

The security-events: write permission is required for SARIF upload. Without it, findings still appear in the PR comment and workflow summary but will not show up in the Security tab.

Inputs

Outputs

Examples

Block PRs that score D or below:

- uses: AgentsID-dev/agentsid@master
  with:
    target: 'npx @your-org/your-mcp-server'
    fail-on-grade: 'D'

Scan a remote server with credentials:

- uses: AgentsID-dev/agentsid@master
  with:
    target: 'https://mcp.example.com/mcp'
    env: |
      API_KEY=${{ secrets.MCP_API_KEY }}
      REGION=us-east-1

Scan multiple servers in parallel (matrix):

jobs:
  scan:
    strategy:
      matrix:
        server:
          - 'npx @your-org/server-a'
          - 'npx @your-org/server-b'
          - 'npx @your-org/server-c'
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      security-events: write
    steps:
      - uses: AgentsID-dev/agentsid@master
        with:
          target: ${{ matrix.server }}

Use the grade in downstream steps:

- uses: AgentsID-dev/agentsid@master
  id: scan
  with:
    target: 'npx @your-org/your-mcp-server'

- run: |
    echo "Grade: ${{ steps.scan.outputs.grade }}"
    echo "Score: ${{ steps.scan.outputs.score }}"
    echo "Critical findings: ${{ steps.scan.outputs.findings-critical }}"

What the scanner checks

Based on 5 published research papers and analysis of more than 15,000 MCP servers across five category grades:

• auth — token handling, credential exposure, unauthenticated tool access
• injection — prompt injection, unicode smuggling, invisible instructions
• input validation — schema gaps, unbounded parameters, type confusion
• output safety — data leakage, unsafe returns, sensitive field exposure
• privilege — overly broad tool scopes, privilege escalation paths

Findings are grouped into a trust score (0–100) and letter grade (A–F), with per-category grades broken out in the PR comment and workflow summary.

Documentation

Self-Hosting

AgentsID is a single FastAPI application backed by PostgreSQL.

git clone https://github.com/AgentsID-dev/agentsid.git
cd agentsid/server
cp .env.example .env  # set DATABASE_URL and SIGNING_SECRET
pip install -e .
uvicorn src.app:app --host 0.0.0.0 --port 8000

Or with Docker:

docker build -t agentsid .
docker run -p 8000:8000 --env-file .env agentsid

Why AgentsID

License

MIT