feat(auth): scoped agent tokens for autonomous AI agents [#028]#319
Merged
feat(auth): scoped agent tokens for autonomous AI agents [#028]#319
Conversation
Design and speckit artifacts for scoped agent tokens feature. Agent tokens allow autonomous AI agents to access MCPProxy with restricted server access, permission tiers, and automatic expiry. ## Artifacts - Design doc: docs/plans/2026-03-06-agent-tokens-design.md - Teams auth design: docs/plans/2026-03-06-mcpproxy-teams-auth-design.md - Spec: specs/028-agent-tokens/spec.md (6 user stories, 20 FRs) - Plan: specs/028-agent-tokens/plan.md - Research: specs/028-agent-tokens/research.md - Data model: specs/028-agent-tokens/data-model.md - API contracts: specs/028-agent-tokens/contracts/agent-tokens-api.yaml - Tasks: specs/028-agent-tokens/tasks.md (43 tasks across 8 phases)
Add the internal/auth package with token generation, HMAC-SHA256 hashing, format validation, permission constants, AuthContext for request-scoped identity propagation, and file-based HMAC key management. Add BBolt storage layer with dual-bucket design (hash->record, name->hash) supporting CRUD, revocation, regeneration, last-used tracking, and token validation with expiry/revocation checks. Includes 37 passing tests covering all functionality with race detection clean. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…Phase 3+4, T010-T022)
Phase 3 (Auth Middleware):
- Add AuthContext injection in apiKeyAuthMiddleware for admin/agent token auth
- Add mcpAuthMiddleware for MCP endpoint agent token scope enforcement
- Support agent token validation via mcp_agt_ prefix in X-API-Key header
- Wire ExtractToken helper for unified token extraction from headers/query params
- Tray connections automatically get admin AuthContext
Phase 4 (REST API Token Management):
- Create internal/httpapi/tokens.go with 5 REST handlers:
- POST /api/v1/tokens (create with name/permissions/servers/expiry validation)
- GET /api/v1/tokens (list without secrets)
- GET /api/v1/tokens/{name} (get single token info)
- DELETE /api/v1/tokens/{name} (revoke)
- POST /api/v1/tokens/{name}/regenerate (regenerate secret)
- All endpoints reject agent token auth with 403
- TokenStore interface for testable storage abstraction
- Validation helpers: name regex, permissions, expiry parsing (max 365d), server names
- Wire storage via SetTokenStore() in server initialization
- Register routes in setupRoutes() under /api/v1/tokens
Tests (27 test functions):
- Token CRUD lifecycle tests (create, list, get, revoke, regenerate)
- Validation: name format, permissions, expiry duration, allowed servers
- Security: agent token rejection (403), admin access, no-store handling (500)
- Validation helper unit tests (name, expiry, allowed servers)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… (Phase 3 completion) Add token CLI subcommands (create/list/show/revoke) and test suites for: - Auth middleware: token extraction priority, agent token validation (valid/expired/revoked/Bearer), admin context propagation, tray bypass - MCP scope enforcement: server access blocking, permission tier checks (read/write/destructive), admin passthrough, upstream server list filtering, quarantine security blocking for agent tokens Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add `mcpproxy token regenerate <name>` CLI command that calls
POST /api/v1/tokens/{name}/regenerate to invalidate the old secret
and generate a new one. Displays the new token with a save warning,
supports -o json output. Includes test verifying command registration
and argument validation.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…e 6, T028-T031) Add auth identity tracking to activity records so tool calls can be attributed to specific agent tokens. Includes: - getAuthMetadata/injectAuthMetadata helpers in mcp.go that extract auth context and inject _auth_ prefixed fields into activity args - Auth metadata injected in handleRetrieveTools, handleCallToolVariant, and legacy handleCallTool before any activity emit calls - AgentName and AuthType filters on ActivityFilter (storage + httpapi) - CLI --agent and --auth-type flags on activity list command - Swagger annotations for new query parameters - Unit tests for getAuthMetadata and injectAuthMetadata functions Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add complete web UI for managing agent tokens: - Token API methods in api.ts (list, create, revoke, regenerate) - AgentTokens.vue view with stats bar, table, create dialog, and token secret display with copy-to-clipboard - Route at /tokens and sidebar navigation entry - TypeScript types for AgentTokenInfo, CreateAgentTokenRequest, CreateAgentTokenResponse Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Deploying mcpproxy-docs with
|
| Latest commit: |
a231680
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://ff3008ad.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://028-agent-tokens.mcpproxy-docs.pages.dev |
Covers motivation, quick start, permission tiers, server scoping, require_mcp_auth enforcement, token management CLI/API, activity logging integration, and security model. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…cation When enabled, the /mcp endpoint rejects unauthenticated requests with 401. Tray/socket connections always bypass this check (OS-level auth). Adds CLI flag --require-mcp-auth and config field require_mcp_auth (default: false). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…responses
Replace text input for allowed_servers with a checkbox list showing all
configured servers with connected/offline badges, plus an "All servers"
wildcard option. Fix token API handlers to wrap responses in the standard
{success, data} envelope expected by the frontend.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tests now unwrap the {success, data} envelope before asserting on
response fields, matching the writeSuccess/NewSuccessResponse changes.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add Auth Type filter (Admin/Agent) and Agent Name filter to Activity Log - Agent name dropdown auto-populates from activity metadata - Fix token secret display: use bg-neutral for dark theme visibility - Fix Copy button: use btn-neutral for dark theme contrast - Fix revoke: handle 204 No Content response in API client Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Windows does not support Unix file permissions, so os.FileMode(0600) assertion always fails. Skip this check on Windows. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 22767352346 --repo smart-mcp-proxy/mcpproxy-go
|
Keep design docs as local-only uncommitted files. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements scoped agent tokens that allow autonomous AI agents to access MCPProxy with restricted server scope and permission tiers. This is a complete feature spanning backend, CLI, REST API, and Web UI.
mcp_agt_prefix, HMAC-SHA256 hashing with server-side key, mandatory expiry (max 365d)/api/v1/tokens— create, list, get, revoke, regeneratemcpproxy token {create,list,show,revoke,regenerate}commandsretrieve_toolsfilters results to scoped servers;call_tool_*blocks out-of-scope access--agentand--auth-typeCLI filtersKey Design Decisions
agent_tokens(hash→JSON) +agent_token_names(name→hash)~/.mcpproxy/.token_key(0600 permissions)Files Changed (39 files, +7360/-22)
internal/auth/agent_token.go,context.go+ testsinternal/storage/agent_tokens.go+ testsinternal/httpapi/tokens.go,server.go+ testsinternal/server/mcp.go+ scope/activity testscmd/mcpproxy/token_cmd.go+ testsAgentTokens.vue,SidebarNav.vue,router/index.ts,api.tsspecs/028-agent-tokens/(spec, plan, research, data-model, contracts, tasks)Test plan
go test -race ./internal/auth/... ./internal/storage/... ./internal/httpapi/... ./internal/server/... ./cmd/mcpproxy/...— all pass./scripts/run-linter.sh— 0 issuesmake build— frontend + backend build succeeds🤖 Generated with Claude Code