{"_id":"@agentauth/sdk","_rev":"5-12b71ec8302247db7ffa7bb22ae1591b","name":"@agentauth/sdk","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@agentauth/sdk","version":"0.1.0","keywords":["agentauth","authentication","identity","mcp","mcp-servers","sdk","ai-agents","model-context-protocol"],"author":{"name":"AgentAuth Team"},"license":"MIT","_id":"@agentauth/sdk@0.1.0","maintainers":[{"name":"agentpaydev","email":"developers@agentpay.me"},{"name":"agentcoredev","email":"developers@agentcore.me"}],"homepage":"https://github.com/agentcorelabs/agentauth#readme","bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"dist":{"shasum":"7129d9223611f0a0e480083fb4faa8fe056fdb53","tarball":"https://registry.npmjs.org/@agentauth/sdk/-/sdk-0.1.0.tgz","fileCount":6,"integrity":"sha512-PSmbuw5ppP6bfv4UPo9oHLnzp6BcIT8OjpCYoyvYY7J8L3KmRhPeVs0lujPpp6Os+1nAsrVfXfPoDy+4Nbih8Q==","signatures":[{"sig":"MEQCICU2LkQDp75DncqGKDMvkdIRWsKPxBLb9wy7J7ZZXJVjAiA3f44i4NEQ/G+b1hEjq1/y9YtkFKw4AZ7TSbTE41nk3w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22992},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"b16d39338eb279939fbf127a619ef323dee449b3","scripts":{"dev":"tsc -w","test":"vitest run","build":"tsc"},"_npmUser":{"name":"agentcoredev","actor":{"name":"agentcoredev","type":"user","email":"developers@agentcore.me"},"email":"developers@agentcore.me"},"repository":{"url":"git+https://github.com/agentcorelabs/agentauth.git","type":"git","directory":"packages/agentauth-sdk"},"_npmVersion":"10.9.0","description":"MCP-native server-side authentication for AI agents.","directories":{},"_nodeVersion":"23.3.0","dependencies":{"@agentauth/core":"0.1.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1750628495277_0.768067314920365","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentauth/sdk","version":"0.1.1","keywords":["agentauth","agentauth-id","authentication","identity","self-authenticating","uuid","mcp","mcp-servers","sdk","ai-agents","model-context-protocol"],"author":{"name":"AgentAuth Team"},"license":"MIT","_id":"@agentauth/sdk@0.1.1","maintainers":[{"name":"agentcoredev","email":"developers@agentcore.me"},{"name":"agentauthdev","email":"developers@agentauth.co"}],"homepage":"https://github.com/agentcorelabs/agentauth#readme","bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"dist":{"shasum":"57d7d09064a0fe1ead84de8e2fc19746d7bc6de0","tarball":"https://registry.npmjs.org/@agentauth/sdk/-/sdk-0.1.1.tgz","fileCount":6,"integrity":"sha512-hn/+2ITsd5Bp+eQxGx+AqihkNeTgDKalP1+3MG8LzvBRBlOcJ2oJXLQyN2s6GUR0VnER1cRwYM7FHFWbNNniQg==","signatures":[{"sig":"MEUCIQCZ1Nlqb0R0iA/V/Efi4/ry+2lxq8IBYE5HCZVZSUd1VwIgStcVPpmzu44i49CPTSyfCh7tXEUYpRO5WaJc+ge3ABM=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":22937},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"bd9fb7af453d65d36762dc2b1de17a8159d1753c","scripts":{"dev":"tsc -w","test":"vitest run","build":"tsc"},"_npmUser":{"name":"agentauthdev","actor":{"name":"agentauthdev","type":"user","email":"developers@agentauth.co"},"email":"developers@agentauth.co"},"repository":{"url":"git+https://github.com/agentcorelabs/agentauth.git","type":"git","directory":"packages/agentauth-sdk"},"_npmVersion":"10.9.0","description":"MCP-native server-side authentication for AI agents.","directories":{},"_nodeVersion":"23.3.0","dependencies":{"@agentauth/core":"0.1.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.1_1751572982968_0.8162408642447845","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@agentauth/sdk","version":"0.1.2","description":"MCP-native identity generation and authentication for AI agents.","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"build":"tsc","dev":"tsc -w","test":"vitest run"},"keywords":["agentauth","agentauth-id","authentication","identity","self-authenticating","uuid","mcp","mcp-servers","sdk","ai-agents","model-context-protocol"],"author":{"name":"AgentAuth Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/agentcorelabs/agentauth.git","directory":"packages/agentauth-sdk"},"homepage":"https://github.com/agentcorelabs/agentauth#readme","bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"type":"module","dependencies":{"@agentauth/core":"0.1.1"},"engines":{"node":">=18.0.0"},"publishConfig":{"access":"public"},"_id":"@agentauth/sdk@0.1.2","gitHead":"c846292bf1d64fffa430d13c4a020c19e3c017a1","_nodeVersion":"23.3.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-cruXIfawWbHmz9eOrphNKgSNICoxFrKeyAUO3fl7QrOPrBfkD5GHjgNI605z9dkkuxU7PVlGSScqiFeci87Zww==","shasum":"c8b48656325ec21937c74aa9c8202a9c3b83e481","tarball":"https://registry.npmjs.org/@agentauth/sdk/-/sdk-0.1.2.tgz","fileCount":6,"unpackedSize":27135,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDffvr7yEiz7hbAA4KLEijXRhkZsO6r1ANGLk4Feh+m3wIgSNaogx9qn0EVDlFdoe/t0a2bytKNnV5zUIhQcKSKttk="}]},"_npmUser":{"name":"agentauthdev","email":"developers@agentauth.co","actor":{"name":"agentauthdev","email":"developers@agentauth.co","type":"user"}},"directories":{},"maintainers":[{"name":"agentcoredev","email":"developers@agentcore.me"},{"name":"agentauthdev","email":"developers@agentauth.co"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.2_1751913723731_0.7041945936528184"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-22T21:41:35.163Z","modified":"2025-07-07T18:42:04.142Z","0.1.0":"2025-06-22T21:41:35.469Z","0.1.1":"2025-07-03T20:03:03.149Z","0.1.2":"2025-07-07T18:42:03.933Z"},"bugs":{"url":"https://github.com/agentcorelabs/agentauth/issues"},"author":{"name":"AgentAuth Team"},"license":"MIT","homepage":"https://github.com/agentcorelabs/agentauth#readme","keywords":["agentauth","agentauth-id","authentication","identity","self-authenticating","uuid","mcp","mcp-servers","sdk","ai-agents","model-context-protocol"],"repository":{"type":"git","url":"git+https://github.com/agentcorelabs/agentauth.git","directory":"packages/agentauth-sdk"},"description":"MCP-native identity generation and authentication for AI agents.","maintainers":[{"name":"agentcoredev","email":"developers@agentcore.me"},{"name":"agentauthdev","email":"developers@agentauth.co"}],"readme":"# @agentauth/sdk: MCP-Native Authentication for AI Agents\n\n[![npm version](https://img.shields.io/npm/v/@agentauth/sdk.svg)](https://www.npmjs.com/package/@agentauth/sdk)\n[![npm downloads](https://img.shields.io/npm/dm/@agentauth/sdk.svg)](https://www.npmjs.com/package/@agentauth/sdk)\n[![Types](https://img.shields.io/npm/types/@agentauth/sdk)](https://www.npmjs.com/package/@agentauth/sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![GitHub stars](https://img.shields.io/github/stars/agentauthco/agentauth?style=social)](https://github.com/agentauthco/agentauth)\n\nServer-side SDK for **AgentAuth ID** — easily authenticate AI agents over MCP using AgentAuth ID, plus generate and manage AgentAuth identities.\n\nAgentAuth 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.\n\nNo logins. No sessions. No extra infra. Just a single UUID for both identity and authentication.\n\nLearn more about AgentAuth at https://github.com/agentauthco/agentauth.\n\n## Why @agentauth/sdk?\n\n- **🔥 Simplest Server-side Usage** — Absolutely the simplest server-side implementation: a single UUID to identify, a single call to verify\n- **🔐 Zero Infrastructure** — No accounts, logins, or session management required\n- **🆔 Stable Agent IDs** — Each agent has its own `AgentAuth ID`, a permanent, verifiable UUID you can use immediately\n- **⚡ Instant Identity Generation** — Create new `AgentAuth ID`s programmatically for any agent with a single call\n- **🌟 Stateless Verification** — One function call to authenticate any request\n- **🛡️ Cryptographically Secure** — Based on industry-standard signatures with replay protection\n- **🔧 Framework Agnostic** — Works with any MCP server, or even any HTTP server\n\n## Installation\n\n```bash\nnpm install @agentauth/sdk\n```\n\n## Quick Start\n\n### Basic Usage\n\nThe SDK provides simple functions for both verifying requests and generating AgentAuth identities:\n\n#### Verify Requests\n\nAuthenticate incoming requests and get the agent's stable UUID:\n\n```typescript\nimport { verify } from '@agentauth/sdk';\n\n// In your request handler\nconst result = verify({ headers: request.headers });\n\nif (result.valid) {\n  const agentId = result.agentauth_id;  // Stable UUID for this agent\n  console.log(`Authenticated agent: ${agentId}`);\n  // Grant access, track usage, personalize response...\n} else {\n  console.log('No valid authentication');\n  // Provide limited access or deny request...\n}\n```\n\n#### Generate AgentAuth Identities\n\nCreate new AgentAuth identities programmatically:\n\n```typescript\nimport { generateIdentity, deriveFromToken } from '@agentauth/sdk';\n\n// Generate a new identity\nconst identity = generateIdentity();\nconsole.log('New AgentAuth ID:', identity.agentauth_id);\nconsole.log('AgentAuth Token:', identity.agentauth_token);\nconsole.log('Address:', identity.agentauth_address);\n\n// Derive identity from existing token\nconst derived = deriveFromToken('aa-...');\nconsole.log('Derived ID:', derived.agentauth_id);\nconsole.log('Derived Address:', derived.agentauth_address);\n```\n\n### MCP Server Integration\n\nHere's how to add AgentAuth ID authentication to your MCP server:\n\n```typescript\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { verify } from '@agentauth/sdk';\nimport { z } from 'zod';\n\nconst server = new McpServer({ name: \"my-server\", version: \"1.0.0\" });\n\n// Helper to get auth context from your transport\nfunction getAuthContext() {\n  // Replace with how your transport exposes HTTP headers\n  const headers = getCurrentRequestHeaders();\n  const authResult = verify({ headers });\n  return authResult.valid ? authResult : null;\n}\n\n// Free tool - enhanced for authenticated users\nserver.tool(\n  \"get-data\",\n  \"Get data (more for authenticated users)\",\n  { query: z.string() },\n  async ({ query }) => {\n    const auth = getAuthContext();\n    \n    if (auth) {\n      // Use the stable UUID for user-specific features\n      console.log(`Agent ${auth.agentauth_id} requested: ${query}`);\n      return { \n        content: [{ \n          type: \"text\", \n          text: `Premium data for agent ${auth.agentauth_id.slice(0, 8)}...` \n        }] \n      };\n    }\n    \n    return { content: [{ type: \"text\", text: \"Basic data (authenticate for more!)\" }] };\n  }\n);\n\n// Premium tool - requires authentication\nserver.tool(\n  \"premium-feature\",\n  \"Access premium features (requires auth)\",\n  {},\n  async () => {\n    const auth = getAuthContext();\n    \n    if (!auth) {\n      return { \n        content: [{ \n          type: \"text\", \n          text: \"🔒 Premium feature requires authentication.\\nGenerate credentials: `agentauth-mcp generate`\" \n        }] \n      };\n    }\n    \n    // Use the UUID in your database, analytics, etc.\n    const agentId = auth.agentauth_id;\n    \n    return { content: [{ type: \"text\", text: `Premium access granted for ${agentId}!` }] };\n  }\n);\n```\n\n💡 Tip: `verify()` is fully stateless and efficient. You can call it safely on every incoming request.\n\n### User Onboarding\n\nEasily let your users know that you are using AgentAuth for authentication and get them started in no time.\n\n**1. User-Facing Materials**\nAdd a blurb like this to your user-facing materials, e.g. docs, GitHub, website, etc.:\n\n```markdown\nThis MCP server uses [AgentAuth](https://agentauth.co) for authentication — a lightweight, self-authenticating identity system for AI agents. No logins, wallets, or centralized accounts necessary.\n\nGenerate your own **AgentAuth Token** (and corresponding **AgentAuth ID**) with [@agentauth/mcp](https://npmjs.com/package/@agentauth/mcp) and connect immediately.\n\nIf you already have an **AgentAuth Token**, include it as an environment variable when configuring this MCP server.\n\n**Example configuration:**\n\\`\\`\\`json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"...\",\n      \"args\": [...],\n      \"env\": {\n        \"AGENTAUTH_TOKEN\": \"aa-...\"\n      }\n    }\n  }\n}\n\\`\\`\\`\n\nLearn more about the open-source AgentAuth authentication standard at https://agentauth.co or https://github.com/agentauthco/agentauth.\n```\n\n**2. MCP Server Tool**\nAdd an `auth-status` tool call to your MCP server that covers authentication options in general, then make sure to include AgentAuth in the response with the following information:\n\n```typescript\nserver.tool(\n  \"auth-status\",\n  \"Check your AgentAuth authentication status and get more info about how to authenticate using AgentAuth\",\n  {},\n  async () => {\n    const auth = getAuthContext();\n    console.error(`🔐 Auth status check - Agent: ${auth?.agentauth_id || 'unauthenticated'}`);\n    \n    const intro = `This MCP server uses AgentAuth for authentication.`;\n\n    // If authenticated, return agent's AgentAuth ID\n    if (auth) {\n      return { \n        content: [{ \n          type: \"text\", \n          text: `${intro}\\n\\nYou are currently **authenticated**. Your **AgentAuth ID** is: \\`${auth.agentauth_id}\\``\n        }] \n      };\n    }\n\n    // Otherwise, return information about how to authenticate\n    const unauthMessage = `${intro}\n\nYou are currently **unauthenticated**.\n\nTo authenticate:\n- If you already have an **AgentAuth Token** for this agent, please include it as an environment variable in this MCP server's configuration file.\n- If not, please generate an **AgentAuth Token** (and corresponding **AgentAuth ID**) using [@agentauth/mcp](https://npmjs.com/package/@agentauth/mcp), then add it as an environment variable in this MCP server's configuration file.\n\n**Example configuration:**\n\\`\\`\\`json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"...\",\n      \"args\": [...],\n      \"env\": {\n        \"AGENTAUTH_TOKEN\": \"aa-...\"\n      }\n    }\n  }\n}\n\\`\\`\\`\n\n**Debugging tips:**\n- If you have already included an **AgentAuth Token** but are still seeing this message, please check that:\n  - Your token is valid and complete (starts with \"aa-\")\n  - It's entered in the correct \"env\" property as shown above\n  - You can verify your token using: \\`agentauth-mcp derive <your_token>\\`\n\nLearn more about the open-source AgentAuth authentication standard at https://agentauth.co`;\n\n    return {\n      content: [{ \n        type: \"text\", \n        text: unauthMessage\n      }] \n    };\n  }\n)\n```\n\n## How It Works\n\n1. **Agent generates token** — Users create an `AgentAuth Token` using `agentauth-mcp generate`\n2. **Token derives ID** — The token deterministically generates a stable `AgentAuth ID` (UUID)\n3. **Requests are signed** — Each request includes cryptographic proof of token ownership\n4. **Server verifies** — Your server calls `verify()` to authenticate and extract the UUID\n5. **Ready to use** — Use the UUID immediately for database storage, access control, etc.\n\nNo server-side state, no account creation, no session management.\n\n## API Reference\n\n### `verify(request, options?)`\n\nVerifies an AgentAuth-authenticated request.\n\n**Parameters:**\n- `request`: Object with a `headers` property containing HTTP headers\n  - Must include AgentAuth headers: `x-agentauth-address`, `x-agentauth-signature`, `x-agentauth-payload`\n- `options`: Optional configuration\n  - `freshness`: Time window in milliseconds for timestamp validation (default: 60000)\n\n**Returns:**\n```typescript\ninterface VerificationResult {\n  valid: boolean;\n  agentauth_id?: string;  // UUID v5 - present only if valid\n}\n```\n\n**Example:**\n```typescript\n// Default 60-second freshness window\nconst result = verify({ headers: req.headers });\n\n// Custom 2-minute freshness window\nconst result = verify({ headers: req.headers }, { freshness: 120000 });\n```\n\n### `generateIdentity()`\n\nGenerates a new AgentAuth identity with token, ID, and address.\n\n**Returns:**\n```typescript\ninterface GeneratedIdentity {\n  agentauth_token: string;    // AgentAuth Token (aa-...)\n  agentauth_id: string;       // UUID v5\n  agentauth_address: string;  // Ethereum-compatible address\n}\n```\n\n**Example:**\n```typescript\nconst identity = generateIdentity();\n// Use identity.agentauth_id for database storage\n// Share identity.agentauth_token with the agent\n```\n\n### `deriveFromToken(agentauth_token)`\n\nDerives an AgentAuth ID and address from an existing token.\n\n**Parameters:**\n- `agentauth_token`: The AgentAuth token (supports aa-, 0x, or raw hex formats)\n\n**Returns:**\n```typescript\ninterface DerivedIdentity {\n  agentauth_id: string;       // UUID v5\n  agentauth_address: string;  // Ethereum-compatible address\n}\n```\n\n**Example:**\n```typescript\nconst derived = deriveFromToken('aa-...');\n// Same token always produces same ID and address\n```\n\n** Technical Flow**\n\n```mermaid\nflowchart\n    A[MCP Client: Agent] -- Makes request to MCP Server --> B[MCP Proxy: @agentauth/mcp]\n    B -- Signs request headers with AgentAuth Token --> C[MCP Server: @agentauth/sdk]\n    C -- Verifies signed headers --> D[Returns AgentAuth ID: UUID]\n```\n\n## Common Patterns\n\n### Express Middleware\n\nCreate middleware that adds authentication context to all requests:\n\n```typescript\nimport express from 'express';\nimport { verify as verifyAgentAuth } from '@agentauth/sdk';\n\nconst app = express();\n\n// AgentAuth middleware - supports both authenticated and unauthenticated\napp.use((req, res, next) => {\n  const result = verifyAgentAuth({ headers: req.headers });\n  \n  if (result.valid) {\n    console.log(`✅ AgentAuth verified: ${result.agentauth_id}`);\n    req.agentauth = result;\n  } else {\n    console.log(`ℹ️ No valid AgentAuth credentials`);\n    // Continue without authentication - supports dual-mode servers\n  }\n  next();\n});\n\n// Use in your routes\napp.get('/api/data', (req, res) => {\n  if (req.agentauth) {\n    res.json({ premium: true, agentId: req.agentauth.agentauth_id });\n  } else {\n    res.json({ premium: false });\n  }\n});\n```\n\n### Database Integration\n\nStore and retrieve agent-specific data:\n\n```typescript\n// First-time agent\nconst auth = getAuthContext();\nif (auth) {\n  await db.agents.upsert({\n    id: auth.agentauth_id,\n    firstSeen: new Date(),\n    lastSeen: new Date(),\n    requestCount: 1\n  });\n}\n\n// Track usage\nif (auth) {\n  await db.usage.create({\n    agentId: auth.agentauth_id,\n    tool: 'premium-feature',\n    timestamp: new Date()\n  });\n}\n```\n\n### Rate Limiting\n\nImplement per-agent rate limits:\n\n```typescript\nconst rateLimits = new Map();\n\nfunction checkRateLimit(agentId: string): boolean {\n  const limit = rateLimits.get(agentId) || { count: 0, reset: Date.now() + 60000 };\n  \n  if (Date.now() > limit.reset) {\n    limit.count = 0;\n    limit.reset = Date.now() + 60000;\n  }\n  \n  limit.count++;\n  rateLimits.set(agentId, limit);\n  \n  return limit.count <= 100; // 100 requests per minute\n}\n\n// In your tool handler\nconst auth = getAuthContext();\nif (auth && !checkRateLimit(auth.agentauth_id)) {\n  return { content: [{ type: \"text\", text: \"Rate limit exceeded. Please try again later.\" }] };\n}\n```\n\n## Security Features\n\n- **Cryptographic signatures** — Uses secp256k1 (Ethereum-standard) for signing\n- **Replay protection** — Timestamp validation prevents replay attacks (60s window)\n- **No token transmission** — Agents never send their raw tokens to servers\n- **Deterministic IDs** — Same token always produces the same UUID\n- **Stateless verification** — No server-side storage needed\n\n## TypeScript Support\n\nFull TypeScript support with exported types:\n\n```typescript\nimport { \n  verify, \n  generateIdentity, \n  deriveFromToken,\n  VerificationResult, \n  GeneratedIdentity,\n  DerivedIdentity,\n  AgentAuthRequest, \n  VerifyOptions \n} from '@agentauth/sdk';\n\n// Type-safe verification\nconst result: VerificationResult = verify({ headers });\n\n// Type-safe identity generation\nconst identity: GeneratedIdentity = generateIdentity();\nconst derived: DerivedIdentity = deriveFromToken(token);\n\n// Custom request type\ninterface MyRequest extends AgentAuthRequest {\n  headers: Record<string, string | string[] | undefined>;\n  body?: any;\n}\n```\n\n## Examples and Testing\n\n### Complete Working Example\n\nWe provide a full working example [weather server](https://github.com/agentauthco/agentauth/tree/main/examples/weather-server) to help with development and testing.\n\n**1. Start the Weather Server:**\n\n```bash\n# Start by cloning the AgentAuth repository\ngit clone https://github.com/agentauthco/agentauth.git\n\n# The example uses AgentAuth workspace dependencies, so install and build from root, first\ncd agentauth\npnpm install\npnpm run build\n\n# Then run build from the weather-server directory\ncd examples/weather-server\npnpm run build  # Dependencies already installed by root pnpm install\n\n# Start the server\npnpm start  # Starts the weather server at http://localhost:8000/mcp using HTTP by default\n```\n\n**2. Configure your MCP Client (e.g. Claude, Cursor, Windsurf, etc.)**\n\n```bash\n# Install the AgentAuth MCP client proxy\nnpm install -g @agentauth/mcp\n```\n\nWithout Authentication:\n```json\n{\n  \"mcpServers\": {\n    \"weather-server-anon\": {\n      \"command\": \"agentauth-mcp\",\n      \"args\": [\"connect\", \"http://localhost:8000/mcp\"]\n    }\n  }\n}\n```\n\nWith Authentication:\n```bash\n# Generate credentials for testing\nagentauth-mcp generate\n# Output:\nAGENTAUTH_ID=...\nAGENTAUTH_TOKEN=aa-...\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"weather-server-auth\": {\n      \"command\": \"agentauth-mcp\",\n      \"args\": [\"connect\", \"http://localhost:8000/mcp\"],\n      \"env\": {\n        \"AGENTAUTH_TOKEN\": \"aa-...\"\n      }\n    }\n  }\n}\n```\n\n**3. Try It Out!**\nStart/Restart your MCP client and try:\n- \"Check my authentication status\"\n- \"Get weather forecast for Oakland, CA\"\n- \"Get weather alerts for CA\"\n\n**What the example demonstrates:**\n- **Tiered authentication** - Free forecasts, premium alerts requiring auth\n- **Dual transport support** - Both HTTP and SSE transport modes\n- **Real-world integration** - External API usage with proper error handling\n- **Production patterns** - Middleware, rate limiting, database-ready UUIDs\n\n👉 **[Full Example Guide](https://github.com/agentauthco/agentauth/tree/main/examples/weather-server/README.md)**\n\n### Testing Resources\n\n**Unit Tests:**\n- This package includes comprehensive unit tests in its [`src/` directory](https://github.com/agentauthco/agentauth/packages/agentauth-sdk/src)\n- Use them to test the core `verify()` function with various scenarios\n- Coverage includes signature validation, timestamp freshness, and error cases\n\n**End-to-End Tests:**\n- Located in the [GitHub repository tests directory](https://github.com/agentauthco/agentauth/tree/main/tests/e2e)\n- Full integration tests with real MCP clients and servers\n- Test complete authentication flows from client to server\n\n## FAQ\n\n**Q: Do agents need to register before using my server?**  \nA: No! AgentAuth is self-authenticating. Any agent with a valid token can connect immediately.\n\n**Q: Can I use the UUID as a primary key in my database?**  \nA: Yes! The UUID is stable and unique per agent. Same token = same UUID always.\n\n**Q: What happens if an agent loses their token?**  \nA: They'll need to generate a new one, which creates a new identity. Treat it like a password.\n\n**Q: Is this compatible with standard MCP servers?**  \nA: Yes! The SDK only adds authentication. Your MCP server works normally otherwise.\n\n**Q: Can I support both authenticated and unauthenticated users?**  \nA: Absolutely! Just check if `verify()` returns valid and provide different experiences.\n\n## Contributing\n\nAgentAuth 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](https://github.com/agentauthco/agentauth/issues). You can also reach out at [developers@agentauth.co](mailto:developers@agentauth.co?subject=Contributing%20to%20AgentAuth) if you are interested in contributing.\n\n## License\n\nMIT License - see [LICENSE](https://github.com/agentauthco/agentauth/blob/main/LICENSE) for details.\n\n## Links\n\n- **Website**: [agentauth.co](https://agentauth.co)\n- **Documentation**: [docs.agentauth.co](https://docs.agentauth.co)\n- **GitHub**: [agentauthco/agentauth](https://github.com/agentauthco/agentauth)\n- **npm**: [@agentauth/sdk](https://www.npmjs.com/package/@agentauth/sdk)\n\n---\n\n**Built by [AgentAuth](https://agentauth.co)** - The Collaboration Layer for AI Agents.","readmeFilename":"README.md"}