AgentAuth ID: The Self-Authenticating UUID for AI Agents

📦 IMPORTANT: The AgentAuth MCP Gateway has moved to its own repository! New location: https://github.com/agentauthco/mcp-gateway This repository now focuses on the core identity primitives and server SDK.

💡 What if all you needed was a UUID?

AgentAuth ID is a self-authenticating UUID for AI agents — a simple, lightweight, open-source primitive for universal identity and trust, designed for use with MCP and agent-native systems.

No logins. No sessions. No extra infra. Just a single UUID for both identity and authentication.

🔥 Why AgentAuth ID?

• Purpose-built for AI agents — Easy to generate and manage, no user accounts needed
• Works across any MCP server — Universal, stable, and designed for use with agent-native communication protocols like MCP
• No extra infra — Zero backend needed for auth — just drop in the SDK

🚀 Quick Start

For AI Agent Users

The AgentAuth MCP Gateway has moved! Please visit the new repository for client setup instructions:

👉 https://github.com/agentauthco/mcp-gateway

The MCP Gateway provides a universal proxy for connecting any MCP client to any remote MCP server with AgentAuth support.

For MCP Server Developers

1. Install the @agentauth/sdk package in your project

# Add to your MCP server
npm install @agentauth/sdk

2. Identify and authenticate agents anywhere in your code

AgentAuth's SDK makes it easy to identify and authenticate agents anywhere in your code. For example:

• On initial connection or in middleware (e.g. to reject unauthenticated agents)
• Beginning of a tool call (e.g. to gate a feature for authenticated users)
• In the middle of a tool call (e.g. to return different results for authenticated and unauthenticated users)

All you need to do is use the SDK's verify method:

• Simultaneously retrieves and authenticates the agent's AgentAuth ID — a stable, unique, verifiable UUID
• Ensures that the request is coming from the controller of that AgentAuth ID

Here is a simple example showing how to use verify to identify and authenticate an agent during a tool call:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { verify } from '@agentauth/sdk';

const server = new McpServer({ name: "my-server", version: "1.0.0" });

// Any tool can check authentication
server.tool("premium-feature", "Premium tool with auth", {}, async () => {
  // Replace `getRequestHeaders` with however your transport exposes HTTP headers
  const authResult = verify({ headers: getRequestHeaders() });
  
  if (authResult.valid) {
    // Store the UUID in your database!
    const agentId = authResult.agentauth_id;
    return { content: [{ type: "text", text: `Premium access granted! Agent ID: ${agentId}` }] };
  }
  
  return { content: [{ type: "text", text: "🔒 This feature requires authentication" }] };
});

✨ Key Features

• 🆔 Self-Authenticating IDs — Each AgentAuth Token generates both a stable UUID (AgentAuth ID) and authentication capability
• ⚡ Single Token Flow — For MCP client users, AgentAuth Token provides complete identity + auth
• 🔐 Zero Infrastructure — For MCP server devs, no accounts, logins, or session management infra required
• 🗄️ Database-Ready UUID — Store and use AgentAuth ID immediately, no extra steps
• 🔧 MCP-Native — Built specifically for communication over MCP specs

📦 AgentAuth Packages Overview

Where to start:

• MCP Client Users — Use @agentauth/mcp to connect any MCP client to any remote MCP server, with universal auth support
• MCP Server Developers — Use @agentauth/sdk to easily add MCP-native authentication to your servers
• Advanced Users — Read @agentauth/core to understand the underlying identity primitives and design decisions

Package	Description	Install	Docs
@agentauth/sdk	Server-side SDK — add MCP-native authentication and identity generation to your servers	npm install @agentauth/sdk	📖 README
@agentauth/core	Core identity primitives — identity generation, signing, and verification using cryptography	(Auto-installed)	📖 README

Additional resources for MCP Server developers:

• Working Example — Complete example with tiered authentication, dual transport support, and real-world integration patterns
• End-to-End Tests — Comprehensive test scenarios demonstrating authentication flows and MCP client integration
• Unit Tests — Individual package tests located in each src/ directory for detailed API testing
• Testing Guide — Testing guide

🏗️ How AgentAuth Works

1. One Agent, One Token: Generate an AgentAuth Token for an agent instantly
2. Automatic Identity: Token automatically derives an AgentAuth ID (a stable, verifiable UUID)
3. Self-Authentication: Every request includes verifiable proof of identity
4. Instant Verification: Servers verify and extract the AgentAuth ID in one step
5. Ready to Use: Use the AgentAuth ID immediately in your database

No additional steps. No account creation. No session management.

Technical Flow

flowchart
    A[MCP Client<br/>AI Agent] -- Make request to MCP Server --> B[MCP Proxy<br/>@agentauth/mcp]
    B -- Sign request headers with AgentAuth Token --> C[MCP Server<br/>@agentauth/sdk]
    C -- Verify signed headers --> D[Return AgentAuth ID<br/>Authenticated UUID]

Loading

🎯 Use Cases

• Premium MCP Tools — Offer authenticated features alongside free tiers
• Usage Tracking — Monitor agent activity with stable, anonymous IDs
• Access Control — Implement tool-level permissions and rate limiting
• Analytics — Understand agent behavior without compromising privacy

🚀 Getting Started

MCP Client Configuration

As an MCP client user, you will be using the @agentauth/mcp package. See the repository for full installation and setup details.

1. **Generate your agent's AgentAuth Token:

npm install -g @agentauth/mcp
agentauth-mcp generate
# Output:
AGENTAUTH_ID=...
AGENTAUTH_TOKEN=aa-...

The generate command generates a unique AgentAuth Token (starts with aa-) for your agent.

The AgentAuth Token is like the password for a corresponding AgentAuth ID — and, since the AgentAuth Token is used to derive the AgentAuth ID, it's all you need to include in your configuration for both identity and auth!

Note

• Store your AgentAuth Token immediately, as it will only be shown to you once each time you use generate
• Treat your AgentAuth Token like your agent's password — store it securely and never share it with anyone

Tip

You can check your corresponding AgentAuth ID anytime using derive <AgentAuth Token>:

agentauth-mcp derive aa-...
# Output: AGENTAUTH_ID=...

2. Add it to your MCP client configuration file:

{
  "mcpServers": {
    "my-server": {
      "command": "agentauth-mcp",
      "args": ["connect", "https://example.com/mcp"],
      "env": {
        "AGENTAUTH_TOKEN": "aa-..."
      }
    }
  }
}

The @agentauth/mcp package is designed to be your universal, long-term proxy for ALL remote MCP server connections. This means that:

• Once added, you can keep this configuration the same for as long as you use the MCP server
• You can use the same configuration for any remote MCP server, even ones that don't use AgentAuth
• You can safely use the same AgentAuth Token when connecting to any MCP server that uses AgentAuth
• Basically, all you need to do is copy and paste the same config for every new remote MCP server you want to connect to (just update the URL after connect)!

Note

• The AgentAuth Token is only ever used locally by the @agentauth/mcp package, and never sent to the MCP server
• The server only receives information to derive your AgentAuth ID and verify that you have the corresponding AgentAuth Token

MCP Server Integration

As an MCP server developer, you will want to install and import the @agentauth/sdk package. See the README there for more details.

Authenticating Requests:

The key method is verify(), which takes request headers and returns the verified AgentAuth UUID of the agent if the request is properly authenticated.

This means that you can authenticate requests on the fly without requiring any a priori "login" in the traditional sense, making the communication process much more streamlined and MCP-native.

• Connections — Authenticate connections immediately (e.g. in middleware) to identify and authenticate agents
• Requests — Authenticate incoming requests at any point (e.g. on receipt, during tool calls, or inline)
• Tool calls — Authenticate at the beginning of tool calls (or even in the middle of one) to provide authentication-based responses

AgentAuth ID as UUID:

Moreover, the AgentAuth ID is a stable, verifiable UUID for any agent, derived from its AgentAuth Token (generated on the client-side), giving it a long-term, universal identity.

This means that you can simply and safely treat the UUID returned by verify as an authenticated user of your service — just like a user ID. For example:

• Create — Create an entry in your DB to identify the agent using its AgentAuth ID (e.g. for first-time users)
• Retrieve — Retrieve the agent in your DB using its AgentAuth ID to read or update properties (e.g. for return users)
• Forward — Forward the AgentAuth ID to third-party services to request additional information or permissions for the agent

Here is a simple example implementation:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { verify } from '@agentauth/sdk';
import { z } from 'zod';

const server = new McpServer({ name: "my-server", version: "1.0.0" });

// Helper to get auth context
function getAuthContext() {
  // Replace with how your transport exposes HTTP headers
  const authResult = verify({ headers: getCurrentRequestHeaders() });
  return authResult.valid ? authResult : null;
}

// Free tool - enhanced for authenticated users
server.tool(
  "get-data",
  "Get data (more for authenticated users)",
  { query: z.string() },
  async ({ query }) => {
    const auth = getAuthContext();
    
    if (auth) {
      // Store/log the agent UUID for analytics!
      console.log(`Agent ${auth.agentauth_id} requested: ${query}`);
      return { 
        content: [{ 
          type: "text", 
          text: `Premium data for agent ${auth.agentauth_id.slice(0, 8)}...` 
        }] 
      };
    }
    
    return { content: [{ type: "text", text: "Basic data (authenticate for more!)" }] };
  }
);

// Premium tool - requires authentication
server.tool(
  "premium-feature",
  "Access premium features (requires auth)",
  {},
  async () => {
    const auth = getAuthContext();
    
    if (!auth) {
      return { 
        content: [{ 
          type: "text", 
          text: "🔒 Premium feature requires authentication.\nGenerate credentials: `agentauth-mcp generate`" 
        }] 
      };
    }
    
    // Use the stable UUID for user-specific features
    const agentId = auth.agentauth_id;
    // Query your database, track usage, etc.
    
    return { content: [{ type: "text", text: `Premium access granted for ${agentId}!` }] };
  }
);

🔒 Security Features

• AgentAuth Token never leaves your machine — Only used locally and only stored in your local config
• Derived identity — Only your derived AgentAuth ID is shared with servers, never tokens
• Timestamp-based replay protection — 60-second window prevents replay attacks
• Cryptographic signatures — Every request is signed with your AgentAuth Token
• No server-side state required — Completely stateless verification

🛠️ Development

Fresh repository clone setup:

# Clone the repository
git clone https://github.com/agentauthco/agentauth.git
cd agentauth

# Install all workspace dependencies (packages, examples, tests)
pnpm install

# Build all packages (required before running examples/tests)
pnpm run build

# Run all package unit tests
pnpm test

# Run e2e integration tests
cd tests/e2e && pnpm test

# Run the example weather server
cd examples/weather-server && pnpm run start  # Starts the weather server at http://localhost:8000/mcp using HTTP by default

Note

This is a pnpm workspace project. You can use workspace:* for local dependencies and pnpm for installation and development.

📚 Documentation

Package Documentation:

• @agentauth/sdk README — Server-side SDK for adding MCP-native authentication
• @agentauth/core README — Core identity primitives and cryptographic functions

MCP Gateway (moved to separate repository):

• @agentauth/mcp — Universal MCP proxy for connecting clients to remote servers

Examples and Testing:

• Working Example — Complete weather server with tiered authentication
• Testing Guide — Comprehensive development and testing documentation
• Tests Directory — Overview of test structure and quick start commands

External Resources:

• Documentation Site — Complete API reference and guides

🤝 Contributing

AgentAuth ID is an early-stage open-source project maintained by the AgentAuth team. We welcome bug reports, feature suggestions, and early feedback via GitHub Issues. You can also reach out at developers@agentauth.co if you are interested in contributing.

📄 License

MIT License — see LICENSE for details.

🔗 Links

• Website — agentauth.co
• Documentation — docs.agentauth.co
• npm — @agentauth
• Issues — GitHub Issues

---

Built by AgentAuth — The Collaboration Layer for AI Agents.