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

Cryptographic Verification: Ed25519 public key verification for all MCP servers
Auto-Detection: Automatic discovery from Claude Desktop config
Manual Declaration: Explicit capability registration without SDK
Capability Tracking: Comprehensive tracking of server capabilities

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

Filesystem MCP:

Read, write, and manipulate files on the local system

GitHub MCP:

Interact with GitHub repositories, issues, and pull requests

Database MCP:

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 | base64

Verification Flow

  1. MCP server registers with public key
  2. Agent requests action from MCP server
  3. MCP server signs response with private key
  4. AIM verifies signature with public key
  5. 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. 1. Block the unauthorized operation
  2. 2. Generate a security alert
  3. 3. Require explicit admin approval to add new capability
  4. 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?