Agent MCP (Admin)

Internal agent infrastructure — 45 MCP tools across 12 domains for 10 autonomous AI agents. This is the private admin system, not the public MCP server.

Overview

LinkTime runs 10 autonomous AI agents that handle support, analytics, infrastructure monitoring, growth, and more. These agents communicate through a private MCP (Model Context Protocol) server that gives them scoped access to platform data and operations.

3-Layer Architecture

🧠

OpenClaw

Agent brains, Slack interface, cron scheduling. Runs on Railway.

🔧

LinkTime MCP

45 tools, budget enforcement, audit logging. This server.

🗄️

PostgreSQL

State, cost tracking, tool call history, audit trail.

Agents call tools viaPOST /api/admin/agent-mcp→ JSON-RPC 2.0

Each agent authenticates with a dedicated API key that grants specific scopes. The server enforces scope-based access control, logs every call to an audit table, and requires explicit confirmation on destructive operations.

Authentication

Agent API Key Format

lt_agent_{agentName}_{64hexChars}

Example: lt_agent_support_a1b2c3d4e5f6... (64 hex characters)

Authentication Flow

Agent sends POST /api/admin/agent-mcp with Authorization: Bearer lt_agent_...
Server validates key format (cheap, no DB hit)
Server hashes key with SHA-256, looks up hash in AgentApiKey table
If valid and active: creates McpHandler with the agent's scopes
Handler processes JSON-RPC request, checking tool scope before execution
Every tool call logged to AgentToolCall table

Scope Model

Format: {domain}:{action} — e.g., analytics:read, bookings:write. Write implies read — an agent with flags:write automatically gets flags:read.

Protocol

The server uses JSON-RPC 2.0 over HTTP POST. All requests go to /api/admin/agent-mcp.

Method	Purpose
initialize	MCP handshake — returns protocol version and server info
ping	Health check
tools/list	Returns tools the agent has access to (filtered by scopes)
tools/call	Execute a tool with arguments (scope check + audit log)

Safety Gates

Scope enforcement — Agent can only call tools matching its scopes
confirm: true — All destructive write tools require explicit confirmation
Field whitelists — Write tools only accept specific fields
Audit trail — Every call logged with agent identity, tool name, input hash, status, latency
Rate limits — Built into the agent key system

Tool Domains

45 tools organized into 12 domains. Full API signatures are in the LLM markdown reference.

Domain	Tools	Scopes	Description
Analytics	9	analytics:read	KPI dashboard, revenue, traffic, booking metrics, signup funnel
Feature Flags	6	flags:read/write	List, check, toggle flags; per-user overrides
Infrastructure	4	infra:read/write	Cron health, system tests, messaging kill switch
Audit	1	audit:read	Cross-user audit log search with filters
Users	7	users:read/write	User lookup, activity, plan changes, settings, disable
Bookings	4	bookings:read/write	List, detail, admin cancel/reschedule with all side effects
Contacts	3	contacts:read/write	Cross-user contact list, detail, metadata updates
Events	3	events:read	Event type listing, detail, availability checking
Budget	2	budget:read	Per-agent daily budget check, global budget status
Codebase	4	codebase:read	GitHub-backed file search, read, directory listing, git history
Email	1	email:write	Branded email sending with per-agent category permissions
Images	1	images:write	AI image generation via Scenario API (Gemini 3.1)
Total	45	17 scopes across 12 domains

Budget System

Every agent has a daily spending cap enforced via the Cap Gate pattern. Agents must call check_budget before taking actions that cost money (LLM calls, email sends, image generation).

Per-Agent Limits

Support agent: $0.20/day (high volume, low cost per call)
All other agents: $5.00/day
Warning threshold at 80% spent

Global Cap

Global daily limit: $50/day
check_global_budget shows cross-agent spend
Budget resets at midnight UTC

Budget Tools

Tool	Scope	Description
check_budget	budget:read	Check remaining budget for the calling agent
check_global_budget	budget:read	View cross-agent budget breakdown and global cap status

Agent Email

Agents can send branded emails via the send_email tool (scope: email:write). Each agent has category restrictions and rate limits to prevent abuse.

Category Permissions

Agent	Allowed Categories
Support	support, transactional, internal
CTO, DevOps	transactional, internal
Orchestrator	support, transactional, internal
Data, SEO	internal only
Growth, Outbound, CS, Content	marketing, internal

Rate Limits

Level 1 (Support, DevOps, Outbound, Orchestrator): 20/day, 5/hour
Level 0 (CTO, Data, SEO, Growth, CS, Content): 5/day, 2/hour

Compliance

Marketing emails include CAN-SPAM headers
RFC 8058 one-click unsubscribe
Opt-out enforcement for marketing category
All sends logged to AgentEmailLog table

Agent Roster

10 agents running on OpenClaw. All 10 connected via Slack with dedicated bot identities.

Agent	Persona	Model	Autonomy	Status
Support	The Front Line	Sonnet	L1	Connected
CTO	The Builder	Opus	L1	Connected
Data	The Analyst	Sonnet	L1	Connected
DevOps	The Guardian	Sonnet	L1	Connected
Orchestrator	The Chief of Staff	Sonnet	L1	Connected
SEO	The Cartographer	Sonnet	L0	Connected
Growth	The Experimenter	Sonnet	L0	Connected
Outbound	The Hunter	Sonnet	L0	Connected
Customer Success	The Gardener	Sonnet	L0	Connected
Content	The Voice	Sonnet	L0	Connected

Connected = Slack app installed, Socket Mode active, agent responding. L0 = connected, read-only / internal-only email. L1 = operates autonomously within scope.

Autonomy Framework

Agent actions are classified by reversibility into three tiers. Higher tiers require more oversight.

T1 — Fully Autonomous

Read-only actions. No human approval needed.

• Reading analytics dashboards
• Listing users, bookings, contacts
• Checking feature flags
• Searching codebase
• Budget checks

T2 — Supervised

Reversible writes. Require confirm: true.

• Toggling feature flags
• Updating user settings
• Updating contact metadata
• Sending emails
• Generating images

T3 — Human-in-the-Loop

Irreversible or high-impact. Orchestrator approval required.

• Cancelling bookings
• Changing user plans
• Disabling user accounts
• Messaging kill switch

Autonomy Levels

L0 — Agent is connected but read-only / internal-only email (5 agents). L1 — Agent operates autonomously within its scope with budget constraints (5 agents). Higher levels (L2+) will be introduced as agents prove reliable.

Scope Reference

17 scopes across 12 domains. Write scopes always imply the corresponding read scope.

Scope	Domain	Tools	Type
analytics:read	Analytics	9	Read
flags:read	Feature Flags	3	Read
flags:write	Feature Flags	3	Write
infra:read	Infrastructure	2	Read
infra:write	Infrastructure	2	Write
audit:read	Audit	1	Read
users:read	Users	4	Read
users:write	Users	3	Write
bookings:read	Bookings	2	Read
bookings:write	Bookings	2	Write
contacts:read	Contacts	2	Read
contacts:write	Contacts	1	Write
events:read	Events	3	Read
budget:read	Budget	2	Read
codebase:read	Codebase	4	Read
email:write	Email	1	Write
images:write	Images	1	Write
Total		45	17 scopes

API Examples

Calling a Tool

POST /api/admin/agent-mcp Authorization: Bearer lt_agent_support_a1b2c3d4... { "jsonrpc": "2.0", "id": "req-1", "method": "tools/call", "params": { "name": "search_users_by_email", "arguments": { "email": "[email protected]" } } }

Success Response

{ "jsonrpc": "2.0", "id": "req-1", "result": { "content": [{ "type": "text", "text": "{\"success\":true,\"data\":{\"users\":[{\"id\":\"clx...\",\"email\":\"[email protected]\",\"name\":\"John Doe\",\"plan\":\"PRO\"}],\"count\":1}}" }] } }

Listing Available Tools

POST /api/admin/agent-mcp Authorization: Bearer lt_agent_support_a1b2c3d4... { "jsonrpc": "2.0", "id": "req-2", "method": "tools/list", "params": {} }

Returns only the tools the authenticated agent has access to, filtered by its key's scopes.

Error Response

{ "jsonrpc": "2.0", "id": "req-3", "error": { "code": -32600, "message": "Scope 'bookings:write' required but agent only has: analytics:read, users:read" } }

Key Files

File	Purpose
src/lib/mcp/types.ts	McpTool, McpToolResult, JsonRpc types
src/lib/mcp/registry.ts	ToolRegistry class (register, scope filter, access check)
src/lib/mcp/handler.ts	JSON-RPC routing, scope enforcement, audit logging
src/lib/mcp/tools.ts	Global registry initialization (imports all 12 domain files)
src/lib/mcp/tools/*.ts	12 domain files: analytics (9), flags (6), infra (4), audit (1), users (7), bookings (4), contacts (3), events (3), budget (2), codebase (4), email (1), images (1)
src/lib/agent-keys.ts	Agent key generation, format validation, display formatting
src/lib/require-agent-key.ts	Authentication middleware with scope checking
src/app/api/admin/agent-mcp/route.ts	HTTP endpoint (POST handler)
src/lib/admin-agents.ts	Agent dashboard service (static roster + Prisma queries)
src/lib/agent-events.ts	Event bus for agent webhook delivery