AgentOS MCP Server

AgentOS MCP Server

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

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

🚀 Quick Install

npx agentos-mcp-server

npm: agentos-mcp-server MCP Registry: io.github.imran-siddique/agentos

Overview

AgentOS MCP Server brings the complete Agent OS safety framework to any MCP-compatible AI assistant including Claude Desktop, GitHub Copilot, Cursor, and more. Create, deploy, and manage policy-compliant autonomous agents through natural conversation.

┌─────────────────────────────────────────────────────────────┐
│           Claude Desktop / Copilot / Cursor                  │
│  ┌────────────────────────────────────────────────────────┐ │
│  │            "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.jsonmacOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonLinux: ~/.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:

1. Create the agent with appropriate configuration
2. Suggest safety policies based on the task
3. Let you test before deployment
4. 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 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

Compliance Templates

🤖 Agent Templates

Data Processing

Communication

Infrastructure

Analytics

⚙️ Configuration

Environment Variables

Policy Modes

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

💻 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

📜 License

MIT License - see LICENSE.