@microsoft/agentos-mcp-server

v3.0.2

Published

3 days ago

Public Preview — AgentOS MCP Server for Claude Desktop: Build, deploy, and manage policy-compliant autonomous agents

0High
0Medium
0Low

microsoft1es

microsoft-oss-releases

mcp model-context-protocol agent-os claude-desktop ai-agents agent-safety policy-enforcement autonomous-agents anthropic

AgentOS MCP Server

[!IMPORTANT] Public Preview — This npm package is a Microsoft-signed public preview release. APIs may change before GA.

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.microsoft/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.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/microsoft/agent-governance-toolkit
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