agentos-mcp-server

AgentOS MCP Server for Claude Desktop

Build safe AI agents with natural language and 0% policy violations

Part of Agent OS - Kernel-level governance for AI agents

Overview

AgentOS MCP Server brings the complete Agent OS safety framework directly into Claude Desktop via the Model Context Protocol (MCP). Create, deploy, and manage policy-compliant autonomous agents through natural conversation with Claude.

┌─────────────────────────────────────────────────────────────┐
│                     Claude Desktop                           │
│  ┌────────────────────────────────────────────────────────┐ │
│  │            "Create an agent that..."                    │ │
│  └──────────────────────┬─────────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
                          │ MCP Protocol
            ┌─────────────▼─────────────┐
            │   🛡️ AgentOS MCP Server   │
            │                           │
            │  • 10 Tools              │
            │  • Policy Engine         │
            │  • Approval Workflows    │
            │  • Audit Logging         │
            │  • Template Library      │
            └─────────────┬─────────────┘
                          │
      ┌───────────────────┼───────────────────┐
      │                   │                   │
┌─────▼─────┐      ┌──────▼──────┐     ┌─────▼─────┐
│  Agents   │      │  Policies   │     │  Audit    │
│  (Local)  │      │  (Enforced) │     │  (Logged) │
└───────────┘      └─────────────┘     └───────────┘

✨ Features

🤖 Natural Language Agent Creation

User: Create an agent that processes customer feedback from support emails daily

Claude: ✅ Agent Created Successfully!

Agent: customer-feedback-processor
✅ Data Source: Email inbox via IMAP
✅ Processing: Sentiment analysis + categorization
✅ Output: Daily summary to Slack
✅ Schedule: Every day at 9 AM

Safety Policies Applied:
🛡️ PII Protection: Customer emails/names anonymized
🛡️ Rate Limiting: Max 1000 emails per run
🛡️ Human Review: Negative sentiment cases flagged

🛡️ Policy Enforcement with 0% Violations

• 6 built-in policies (PII, rate-limiting, cost-control, data-deletion, secrets, human-review)
• Real-time policy evaluation
• Automatic blocking of violations
• Clear explanations and alternatives

✅ Human-in-the-Loop Approval Workflows

• Risk-based approval requirements
• Multi-party approval for critical actions
• Email/Slack notifications
• Expiration handling

📊 Complete Audit Trail

• Every action logged immutably
• Policy evaluations recorded
• Compliance report generation
• Export for auditors

📋 Template Library

• 10+ agent templates (data processor, email assistant, backup, scraper, etc.)
• 6+ policy templates (GDPR, SOC 2, HIPAA, PCI DSS, etc.)
• Industry-specific compliance frameworks

🏛️ Compliance Ready

• SOC 2 - Security & availability controls
• GDPR - EU data protection
• HIPAA - Healthcare data privacy
• PCI DSS - Payment card security
• CCPA - California privacy
• NIST - Cybersecurity framework
• ISO 27001 - Information security
• FedRAMP - Federal authorization

🚀 Quick Start

Step 1: Configure Claude Desktop

Add to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agentos": {
      "command": "npx",
      "args": ["-y", "@agentos/mcp-server"],
      "env": {
        "AGENTOS_POLICY_MODE": "strict"
      }
    }
  }
}

Step 2: Restart Claude Desktop

Close and reopen Claude Desktop to load the MCP server.

Step 3: Start Building Agents!

Just ask Claude naturally:

"Create an agent that backs up my Documents folder to Google Drive every night"

Claude will:

• Create the agent with appropriate configuration
• Suggest safety policies based on the task
• Let you test before deployment
• Deploy with monitoring enabled

💬 Example Conversations

Creating a Data Processing Agent

User: I need an agent that processes customer feedback from support emails daily

Claude: ✅ Agent Created Successfully!

Agent: customer-feedback-processor
ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Status: draft
Language: python

Task:
Process customer feedback from support emails daily

Workflow Steps:
1. connect_email: email.connect
2. process_data: execute
3. output_results: output

Safety Policies Applied:
🛡️ PII Protection: Customer emails/names anonymized
🛡️ Rate Limiting: Max 1000 emails per run
🛡️ Human Review: Negative sentiment cases flagged

Next Steps:
1. Use `test_agent` to run a dry-run test
2. Use `attach_policy` to add more safety policies
3. Use `deploy_agent` when ready to run

Testing Before Deployment

User: Test this agent with a scenario of processing 100 emails

Claude: ✅ Test PASSED

Agent: customer-feedback-processor
Scenario: Process 100 customer emails
Mode: Dry Run (no changes)

Configuration Check: ✅ Valid
Workflow Check: ✅ Valid (3 steps)

Policy Evaluation: ✅ No violations detected

Warnings:
⚠️  PII access logged

Resource Estimates:
- Duration: ~30 seconds
- Cost: $0.05

Next Step: Use `deploy_agent` to deploy this agent.

Checking Compliance

User: Check if this agent is SOC 2 compliant

Claude: # Compliance Report: SOC2

Agent: customer-feedback-processor
Framework: SOC2
Date: 2026-01-30

## Summary
✅ COMPLIANT
Score: 100% (4/4 controls passed)

## Control Assessment

✅ CC6.1: Logical Access Controls
   Restrict logical access to information assets
   Evidence: Policy enforcement enabled, Access logging active

✅ CC6.6: Security Event Monitoring
   Detect and respond to security events
   Evidence: Audit logging enabled, Event timestamps recorded

✅ CC7.2: Incident Response
   Respond to security incidents
   Evidence: Human review enabled, Escalation procedures in place

✅ CC8.1: Change Management
   Manage changes to system components
   Evidence: Deployment approval required, Version control enabled

Creating Custom Policies

User: Create a policy that blocks access to customer credit card data

Claude: ✅ Custom Policy Created

Policy: Block Access To Customer
ID: custom-a1b2c3d4
Category: security

Description:
Block access to customer credit card data

Rules Generated (1):

🟠 custom_block_rule [high]
   Block actions based on: block access to customer credit card data
   Action: deny

Usage:
1. Attach to agent: `attach_policy` with policyId "custom-a1b2c3d4"
2. Test enforcement: `test_agent` with policy scenarios
3. View active policies: `get_agent_status`

🔧 Available Tools

Tool	Description
create_agent	Create agent from natural language description
attach_policy	Attach safety policies to agents
test_agent	Dry-run test before deployment
deploy_agent	Deploy agent locally or to cloud
get_agent_status	Get agent status and metrics
list_templates	Browse agent and policy templates
request_approval	Create approval request for sensitive actions
audit_log	Query audit trail
create_policy	Create custom policy from description
check_compliance	Check against compliance frameworks

Tool Details

create_agent

Create a new AI agent from a natural language description with automatic policy recommendations.

Parameters:

Parameter	Type	Required	Description
description	string	✅	Natural language description of agent task
policies	string[]		Policy templates to apply
approvalRequired	boolean		Require human approval before execution
language	string		python, typescript, javascript, go
schedule	string		Cron schedule for recurring execution

attach_policy

Attach safety policies to an agent with conflict detection.

Parameters:

Parameter	Type	Required	Description
agentId	string	✅	Agent ID to attach policy to
policyId	string	✅	Policy template ID
customRules	object[]		Additional custom rules

test_agent

Run a dry-run test with simulated scenarios.

Parameters:

Parameter	Type	Required	Description
agentId	string	✅	Agent ID to test
scenario	string	✅	Test scenario description
mockData	object		Mock data for testing
dryRun	boolean		Run without side effects (default: true)

deploy_agent

Deploy an agent to local or cloud environment.

Parameters:

Parameter	Type	Required	Description
agentId	string	✅	Agent ID to deploy
environment	string		local or cloud
autoStart	boolean		Start immediately after deployment

check_compliance

Check an agent against regulatory frameworks.

Parameters:

Parameter	Type	Required	Description
agentId	string	✅	Agent ID to check
framework	string	✅	SOC2, GDPR, HIPAA, PCI_DSS, CCPA, NIST, ISO27001, FEDRAMP
generateReport	boolean		Generate detailed report

📋 Policy Templates

Built-in Security Policies

Policy ID	Name	Description
pii-protection	PII Protection	Protects personally identifiable information (GDPR)
rate-limiting	Rate Limiting	Prevents resource abuse through rate limits
cost-control	Cost Control	Prevents runaway costs from automation
data-deletion	Data Deletion Safety	Prevents accidental data loss
secrets-protection	Secrets Protection	Prevents exposure of credentials
human-review	Human Review Required	Requires approval for sensitive actions

Compliance Templates

Template ID	Framework	Description
gdpr-compliance	GDPR	EU General Data Protection Regulation
soc2-security	SOC 2	SOC 2 Type II security controls
hipaa-healthcare	HIPAA	Healthcare data privacy (PHI protection)
pci-dss-payments	PCI DSS	Payment card data security
read-only-access	Security	Restricts database to read-only
production-safety	Operations	Extra safeguards for production

🤖 Agent Templates

Data Processing

Template	Description	Default Policies
data-processor	Processes and transforms data files	rate-limiting, cost-control
web-scraper	Scrapes websites for data collection	rate-limiting, cost-control
report-generator	Generates periodic reports	pii-protection, rate-limiting

Communication

Template	Description	Default Policies
email-assistant	Monitors and processes emails	pii-protection, human-review
slack-bot	Automated Slack notifications	human-review, rate-limiting

Infrastructure

Template	Description	Default Policies
backup-agent	Backs up files to cloud storage	cost-control
api-monitor	Monitors API health and performance	rate-limiting
file-organizer	Organizes files based on rules	data-deletion

Analytics

Template	Description	Default Policies
database-analyst	Queries databases and generates reports	data-deletion, pii-protection
content-moderator	Moderates user-generated content	human-review, pii-protection

⚙️ Configuration

Environment Variables

Variable	Description	Default
AGENTOS_API_KEY	API key for cloud features	(none)
AGENTOS_POLICY_MODE	strict or permissive	strict
AGENTOS_DATA_DIR	Local data directory	.agentos
AGENTOS_LOG_LEVEL	debug, info, warn, error	info

Policy Modes

Mode	Behavior
strict	Any policy violation blocks the action
permissive	Only critical violations block (warnings logged)

Data Storage

All data is stored locally in the AGENTOS_DATA_DIR:

.agentos/
├── agents/           # Agent configurations
│   └── {id}.json
├── approvals/        # Approval requests
│   └── {id}.json
└── audit/            # Audit logs (JSONL format)
    └── {date}.jsonl

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Desktop                           │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                    Claude AI Model                      │ │
│  │     Natural language understanding & orchestration      │ │
│  └──────────────────────┬─────────────────────────────────┘ │
│                         │ MCP Protocol                       │
│  ┌──────────────────────▼─────────────────────────────────┐ │
│  │                    MCP Client                           │ │
│  │          Tool discovery & request handling              │ │
│  └──────────────────────┬─────────────────────────────────┘ │
└─────────────────────────┼───────────────────────────────────┘
                          │ stdio
┌─────────────────────────▼───────────────────────────────────┐
│               @agentos/mcp-server (Node.js)                 │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                    MCP Server                           │ │
│  │            Tool/Resource/Prompt handlers                │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐  │
│  │  Agent   │ │  Policy  │ │ Approval │ │    Audit      │  │
│  │ Manager  │ │  Engine  │ │ Workflow │ │   Logger      │  │
│  └──────────┘ └──────────┘ └──────────┘ └───────────────┘  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │              Template Library (50+ templates)           │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
                          │ HTTPS (optional)
┌─────────────────────────▼───────────────────────────────────┐
│              AgentOS Cloud Platform (Future)                │
│     • Persistent storage  • Multi-tenant  • Enterprise      │
└─────────────────────────────────────────────────────────────┘

🔒 Security

Feature	Description
Policy Enforcement	All actions validated against policies before execution
Data Redaction	Sensitive data automatically redacted from logs
Secret Protection	Secrets never stored in plain text
Audit Trail	Complete immutable log for compliance
Human Approval	Required for high-risk operations
Local-First	All data stored locally by default

💻 Development

Local Development

# Clone the repository
git clone https://github.com/imran-siddique/agent-os
cd agent-os/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in stdio mode (for Claude Desktop)
npm start -- --stdio

# Run in HTTP mode (for development)
npm start -- --http --port 3000

Project Structure

packages/mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── cli.ts                # CLI with --stdio/--http modes
│   ├── server.ts             # MCP server implementation
│   ├── tools/                # 10 MCP tools
│   │   ├── create-agent.ts
│   │   ├── attach-policy.ts
│   │   ├── test-agent.ts
│   │   ├── deploy-agent.ts
│   │   ├── get-agent-status.ts
│   │   ├── list-templates.ts
│   │   ├── request-approval.ts
│   │   ├── audit-log.ts
│   │   ├── create-policy.ts
│   │   └── check-compliance.ts
│   ├── services/             # Core business logic
│   │   ├── agent-manager.ts
│   │   ├── policy-engine.ts
│   │   ├── approval-workflow.ts
│   │   ├── audit-logger.ts
│   │   └── template-library.ts
│   ├── prompts/              # MCP prompts
│   └── types/                # TypeScript definitions
├── package.json
├── tsconfig.json
└── README.md

Running Tests

npm test
npm run test:coverage

📊 Performance

Metric	Target
MCP server startup	<2 seconds
Tool response time	<500ms (p95)
Memory footprint	<100MB
Policy evaluation	<50ms

📜 License

MIT License - see LICENSE.

Build safe AI agents with AgentOS

GitHub · Documentation · Report Issue

Made with 🛡️ by the Agent OS team