MCP Server Registration & Management
Model Context Protocol (MCP) servers extend AI agent capabilities. AIM provides comprehensive registration, verification, and management for MCP servers with cryptographic security.
Key Features
What are MCP Servers?
MCP servers are external services that AI agents connect to for extended capabilities. They provide tools and resources that agents can use to interact with external systems, databases, APIs, and more.
Common MCP Server Types
Read, write, and manipulate files on the local system
Interact with GitHub repositories, issues, and pull requests
Query and modify databases with proper access controls
Registration Methods
🎯 Method 1: Automatic Detection from Claude Desktop
AIM can automatically detect and register MCP servers from your Claude Desktop configuration.
Step 1: Configure Claude Desktop
Add MCP servers to your Claude Desktop config:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["@modelcontextprotocol/server-filesystem", "/Users/alice/data"]
},
"github": {
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}Step 2: Auto-Detect with AIM
curl -X POST https://aim.example.com/api/v1/agents/agent_123/mcp-servers/detect \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"config_path": "~/Library/Application Support/Claude/claude_desktop_config.json"
}'Python SDK Auto-Detection
from aim_sdk import secure
# Register agent
agent = secure("my-agent")
# Auto-detect MCP servers from Claude Desktop
detected = agent.detect_mcp_servers()
print(f"Detected {len(detected)} MCP servers")
# Servers are automatically registered and verified
for server in detected:
print(f"✅ {server.name}: {server.capabilities}")🔧 Method 2: Manual Registration with API
Manually register MCP servers and declare their capabilities - perfect when not using the Python SDK.
Register MCP Servers
curl -X POST https://aim.example.com/api/v1/agents/agent_123/mcp-servers \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"mcp_servers": [
{
"name": "filesystem-mcp",
"url": "npx:@modelcontextprotocol/server-filesystem",
"public_key": "ed25519:MCowBQYDK2VwAyEA...",
"capabilities": [
"file_read",
"file_write",
"directory_list",
"file_search"
],
"metadata": {
"base_path": "/Users/alice/data",
"read_only": false
}
},
{
"name": "github-mcp",
"url": "npx:@modelcontextprotocol/server-github",
"public_key": "ed25519:MCowBQYDK2VwAyEB...",
"capabilities": [
"repo_read",
"repo_write",
"issue_create",
"pr_create",
"pr_review"
],
"metadata": {
"org": "acme-corp",
"scope": "private"
}
}
]
}'📋 Method 3: Manual Capability Declaration
Explicitly declare agent capabilities without SDK - useful for custom integrations and non-Python agents.
Declare Capabilities Directly
Perfect for agents not using the Python SDK:
curl -X POST https://aim.example.com/api/v1/agents/agent_123/capabilities \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"capabilities": [
{
"name": "database_read",
"resource": "production_db",
"permissions": ["SELECT"],
"mcp_server": "database-mcp",
"conditions": {
"tables": ["users", "orders"],
"time_window": "09:00-18:00",
"rate_limit": 1000
}
},
{
"name": "file_system_access",
"resource": "/data/reports",
"permissions": ["read", "write"],
"mcp_server": "filesystem-mcp",
"conditions": {
"file_types": [".csv", ".json", ".txt"],
"max_file_size": "10MB"
}
},
{
"name": "github_operations",
"resource": "acme-corp/*",
"permissions": ["read", "pr_create"],
"mcp_server": "github-mcp",
"requires_approval": true
}
]
}'Node.js/TypeScript Example
// Manual capability registration from Node.js
import axios from 'axios';
async function registerCapabilities(agentId: string, token: string) {
const response = await axios.post(
`https://aim.example.com/api/v1/agents/${agentId}/capabilities`,
{
capabilities: [
{
name: 'api_call',
resource: 'openai_api',
permissions: ['completion', 'embedding'],
mcp_server: 'openai-mcp',
conditions: {
models: ['gpt-4', 'text-embedding-3'],
max_tokens: 4000,
rate_limit: 100
}
}
]
},
{
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
}
}
);
console.log('Capabilities registered:', response.data);
}Go Example
// Manual capability registration from Go
package main
import (
"bytes"
"encoding/json"
"net/http"
)
type Capability struct {
Name string `json:"name"`
Resource string `json:"resource"`
Permissions []string `json:"permissions"`
MCPServer string `json:"mcp_server"`
Conditions map[string]interface{} `json:"conditions"`
}
func registerCapabilities(agentID, token string) error {
capabilities := []Capability{
{
Name: "s3_access",
Resource: "s3://my-bucket",
Permissions: []string{"read", "write"},
MCPServer: "aws-mcp",
Conditions: map[string]interface{}{
"prefix": "data/",
"max_size": "100MB",
},
},
}
payload, _ := json.Marshal(map[string]interface{}{
"capabilities": capabilities,
})
req, _ := http.NewRequest("POST",
"https://aim.example.com/api/v1/agents/"+agentID+"/capabilities",
bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
return err
}MCP Server Verification
Ed25519 Cryptographic Verification
All MCP servers are verified using Ed25519 public key cryptography to ensure authenticity and prevent tampering.
Generate Ed25519 Keys for MCP Server
# Generate Ed25519 key pair
openssl genpkey -algorithm ED25519 -out mcp_private.pem
openssl pkey -in mcp_private.pem -pubout -out mcp_public.pem
# Convert to base64 for registration
cat mcp_public.pem | base64Verification Flow
- MCP server registers with public key
- Agent requests action from MCP server
- MCP server signs response with private key
- AIM verifies signature with public key
- Action is allowed only if verification succeeds
MCP Server Attestation
AIM cryptographically verifies every MCP (Model Context Protocol) server your agents connect to using Ed25519 digital signatures. This ensures that only trusted, verified servers can interact with your agents and detects any unauthorized capability changes.
What Gets Verified
- • MCP Server Identity: Ed25519 public key verification
- • Declared Capabilities: read_files, execute_code, database_access, etc.
- • Capability Drift Detection: Alerts when capabilities change unexpectedly
- • Connection Patterns: Frequency and usage analysis
When Attestation Fails
- • Invalid Signature: Server identity cannot be verified
- • Capability Drift: Server declares new capabilities not originally registered
- • Expired Keys: Ed25519 keys have exceeded rotation period
- • Policy Violation: Server attempts unauthorized operations
🔍 Capability Drift Detection
AIM continuously monitors MCP servers for capability drift - when a server attempts to use capabilities not declared during registration.
Example: If a filesystem MCP was registered with only read_files, but later attempts to use write_files, AIM will:
- 1. Block the unauthorized operation
- 2. Generate a security alert
- 3. Require explicit admin approval to add new capability
- 4. Log the violation for audit purposes
🎯 Auto-Discovery with Attestation
When AIM auto-discovers MCP servers from Claude Desktop config, it automatically:
✅ Discovery Phase
- • Parse Claude Desktop config file
- • Extract MCP server declarations
- • Identify command, args, and environment
- • Detect declared capabilities from metadata
🔒 Verification Phase
- • Request Ed25519 public key from each server
- • Verify cryptographic signatures
- • Register baseline capabilities
- • Enable continuous drift monitoring
Attestation in Practice
Python: Check MCP Server Attestation Status
from aim_sdk import secure
agent = secure("my-agent")
# Get all registered MCP servers with attestation status
servers = agent.list_mcp_servers()
for server in servers:
print(f"Server: {server.name}")
print(f" Verified: {server.is_verified}")
print(f" Public Key: {server.public_key[:20]}...")
print(f" Capabilities: {', '.join(server.capabilities)}")
print(f" Drift Detected: {server.capability_drift_detected}")
print(f" Last Verified: {server.last_verification_time}")
print()Handling Capability Drift Events
from aim_sdk import secure, events
agent = secure("my-agent")
# Register event handler for capability drift
@agent.on("mcp_capability_drift")
def handle_drift(event):
"""Called when MCP server attempts unauthorized capability"""
print(f"⚠️ Capability drift detected!")
print(f"Server: {event.server_name}")
print(f"Attempted capability: {event.new_capability}")
print(f"Registered capabilities: {event.registered_capabilities}")
# Option 1: Auto-approve low-risk capabilities
if event.new_capability in ["read_only_operations"]:
agent.approve_capability(event.server_name, event.new_capability)
print("✅ Auto-approved low-risk capability")
# Option 2: Request admin approval
else:
agent.request_admin_approval(
server=event.server_name,
capability=event.new_capability,
reason=f"Drift detected from baseline"
)
print("📧 Admin approval requested")
# Agent continues to run with drift protection
agent.start()REST API: Get Attestation Details
# Get detailed attestation report for MCP server
curl -X GET https://aim.example.com/api/v1/agents/agent_123/mcp-servers/filesystem-mcp/attestation \
-H "Authorization: Bearer {token}"
# Response:
{
"server_name": "filesystem-mcp",
"is_verified": true,
"public_key": "ed25519:MCowBQYDK2VwAyEA...",
"registered_capabilities": [
"file_read",
"file_write",
"directory_list"
],
"capability_drift_detected": false,
"last_verification": "2025-01-24T10:30:00Z",
"verification_history": [
{
"timestamp": "2025-01-24T10:30:00Z",
"status": "verified",
"signature_valid": true
}
],
"usage_stats": {
"total_requests": 1523,
"failed_verifications": 0,
"last_used": "2025-01-24T10:25:00Z"
}
}Security Policies for MCP Servers
Security Policy Configuration
Define granular security policies for MCP server access:
curl -X POST https://aim.example.com/api/v1/security/policies \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"name": "MCP Server Access Policy",
"description": "Controls access to MCP servers",
"rules": [
{
"mcp_server": "filesystem-mcp",
"allowed_paths": ["/data/public", "/data/shared"],
"denied_paths": ["/etc", "/system"],
"allowed_operations": ["read"],
"conditions": {
"trust_score_min": 75,
"agent_verified": true,
"time_window": "business_hours"
}
},
{
"mcp_server": "database-mcp",
"allowed_databases": ["analytics"],
"allowed_tables": ["events", "metrics"],
"allowed_operations": ["SELECT"],
"conditions": {
"trust_score_min": 85,
"requires_approval": true
}
}
],
"enforcement": "strict",
"alert_on_violation": true
}'Best Practices
✅ Do
- • Always use Ed25519 keys for MCP servers
- • Implement least-privilege access policies
- • Regularly rotate MCP server keys
- • Monitor MCP server access logs
- • Use auto-detection when possible
- • Define clear capability boundaries
❌ Don\'t
- • Share MCP server private keys
- • Grant blanket access to all resources
- • Skip verification for "trusted" servers
- • Hardcode credentials in code
- • Ignore security alerts
- • Use weak or no authentication
Monitoring & Analytics
📊 Track MCP Server Usage
Monitor all MCP server interactions in real-time:
# Get MCP server usage analytics
curl -X GET https://aim.example.com/api/v1/analytics/mcp-servers?period=7d \
-H "Authorization: Bearer {token}"
# Response includes:
{
"total_requests": 15234,
"unique_agents": 42,
"top_servers": [
{"name": "filesystem-mcp", "requests": 8421, "errors": 12},
{"name": "github-mcp", "requests": 4523, "errors": 3}
],
"capability_usage": {
"file_read": 6234,
"file_write": 2187,
"repo_read": 3421
},
"security_events": 7,
"average_response_time": "127ms"
}🚀 Next Steps
Ready to integrate MCP servers with your AI agents?