MCP Server Registration

Overview

This guide covers the complete process of registering Model Context Protocol (MCP) servers with the Ascend governance platform. Registered MCP servers have their tool calls evaluated, logged, and controlled according to organizational security policies.

Key Capabilities

Multi-Transport Support: Register stdio, HTTP, and WebSocket-based MCP servers
Tool Discovery: Automatic discovery of server tools, prompts, and resources
Governance Configuration: Per-server governance settings and tool policies
Health Monitoring: Track server availability and performance
Lifecycle Management: Activate, deactivate, and delete server registrations

How It Works

Registration Workflow

┌─────────────────────────────────────────────────────────────────────────────┐
│                       MCP SERVER REGISTRATION FLOW                           │
└─────────────────────────────────────────────────────────────────────────────┘

Step 1: Register Server
┌───────────────────┐
│  POST /api/       │
│  registry/        │──────> Server Created (inactive by default)
│  mcp-servers      │
└───────────────────┘

Step 2: Configure Governance
┌───────────────────┐
│  PUT /api/        │
│  registry/        │──────> Configure tools, policies, risk overrides
│  mcp-servers/{id} │
└───────────────────┘

Step 3: Admin Activation
┌───────────────────┐
│  POST /api/       │
│  registry/        │──────> Server Activated
│  mcp-servers/     │
│  {id}/activate    │
└───────────────────┘

Step 4: Governance Active
┌───────────────────┐
│  Tool calls       │
│  evaluated by     │──────> Policy Engine
│  Ascend           │
└───────────────────┘

Transport Types

Transport	Use Case	Configuration
`stdio`	Local MCP servers, CLI tools	Command path, arguments
`http`	Remote MCP servers, microservices	URL, headers, auth
`websocket`	Real-time bidirectional	URL, protocols

Server States

State	Description	Tool Governance
`inactive`	Registered but not activated	No governance
`active`	Fully operational	Full governance
`degraded`	Health issues detected	Governance continues
`offline`	Server unreachable	Fail-closed (deny all)

Configuration

Required Fields

Field	Type	Description
`server_name`	string	Unique identifier (max 255 chars)
`display_name`	string	Human-readable name (max 255 chars)

Optional Fields

Field	Type	Default	Description
`description`	string	null	Server description
`server_url`	string	null	Server endpoint URL
`transport_type`	string	"stdio"	Transport type
`connection_config`	object		Transport-specific config
`governance_enabled`	boolean	true	Enable governance
`auto_approve_tools`	array	[]	Auto-approved tools
`blocked_tools`	array	[]	Blocked tools
`tool_risk_overrides`	object		Per-tool risk scores

Transport Configuration

stdio Transport

{
  "transport_type": "stdio",
  "connection_config": {
    "command": "/usr/local/bin/mcp-server",
    "args": ["--mode", "production"],
    "env": {
      "LOG_LEVEL": "info"
    },
    "cwd": "/opt/mcp"
  }
}

HTTP Transport

{
  "transport_type": "http",
  "server_url": "https://mcp.internal.company.com/api",
  "connection_config": {
    "headers": {
      "X-API-Key": "${MCP_API_KEY}"
    },
    "timeout_seconds": 30,
    "retry_count": 3,
    "verify_ssl": true
  }
}

WebSocket Transport

{
  "transport_type": "websocket",
  "server_url": "wss://mcp.internal.company.com/ws",
  "connection_config": {
    "protocols": ["mcp-v1"],
    "ping_interval_seconds": 30,
    "reconnect_attempts": 5,
    "headers": {
      "Authorization": "Bearer ${MCP_TOKEN}"
    }
  }
}

Usage Examples

Register stdio Server (Python SDK)

from ascend import AscendClient

client = AscendClient(api_key="your-api-key")

# Register a local stdio-based MCP server
server = client.mcp_servers.register(
    server_name="local-file-tools",
    display_name="Local File Tools",
    description="File system operations for local development",
    transport_type="stdio",
    connection_config={
        "command": "/usr/local/bin/file-mcp-server",
        "args": ["--sandbox", "/home/user/workspace"],
        "env": {"LOG_LEVEL": "info"}
    },

    # Governance settings
    governance_enabled=True,
    auto_approve_tools=["read_file", "list_directory"],
    blocked_tools=["delete_file", "execute_shell"],
    tool_risk_overrides={
        "write_file": 60,
        "create_directory": 40
    }
)

print(f"Server registered: {server.server_name}")

Register HTTP Server (Python SDK)

from ascend import AscendClient

client = AscendClient(api_key="your-api-key")

# Register a remote HTTP-based MCP server
server = client.mcp_servers.register(
    server_name="production-db-tools",
    display_name="Production Database Tools",
    description="Read-only database query tools for production",
    transport_type="http",
    server_url="https://db-mcp.internal.company.com/api",
    connection_config={
        "headers": {
            "X-API-Key": "${DB_MCP_API_KEY}"
        },
        "timeout_seconds": 60,
        "verify_ssl": True
    },

    governance_enabled=True,
    auto_approve_tools=["select_query", "describe_table"],
    blocked_tools=[
        "insert_row",
        "update_row",
        "delete_row",
        "drop_table",
        "truncate_table"
    ]
)

Register MCP Server (cURL)

# Register a new MCP server
curl -X POST https://api.ascend.security/api/registry/mcp-servers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "server_name": "code-analysis-tools",
    "display_name": "Code Analysis Tools",
    "description": "Static code analysis and security scanning tools",
    "transport_type": "http",
    "server_url": "https://code-mcp.internal.company.com",
    "connection_config": {
      "headers": {
        "Authorization": "Bearer TOKEN"
      },
      "timeout_seconds": 120
    },
    "governance_enabled": true,
    "auto_approve_tools": ["analyze_syntax", "check_formatting", "lint_code"],
    "blocked_tools": ["execute_code", "modify_file"],
    "tool_risk_overrides": {
      "security_scan": 55,
      "dependency_check": 45
    }
  }'

List All MCP Servers

curl -X GET https://api.ascend.security/api/registry/mcp-servers \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "success": true,
#   "servers": [
#     {
#       "id": 1,
#       "server_name": "local-file-tools",
#       "display_name": "Local File Tools",
#       "transport_type": "stdio",
#       "governance_enabled": true,
#       "is_active": true,
#       "health_status": "online",
#       "discovered_tools": [...],
#       "auto_approve_tools": ["read_file", "list_directory"],
#       "blocked_tools": ["delete_file"]
#     }
#   ]
# }

Get Server Details

curl -X GET https://api.ascend.security/api/registry/mcp-servers/local-file-tools \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response:
# {
#   "success": true,
#   "server": {
#     "id": 1,
#     "server_name": "local-file-tools",
#     "display_name": "Local File Tools",
#     "description": "File system operations for local development",
#     "server_url": null,
#     "transport_type": "stdio",
#     "connection_config": {
#       "command": "/usr/local/bin/file-mcp-server",
#       "args": ["--sandbox", "/home/user/workspace"]
#     },
#     "governance_enabled": true,
#     "is_active": true,
#     "health_status": "online",
#     "discovered_tools": [
#       {"name": "read_file", "description": "Read file contents"},
#       {"name": "write_file", "description": "Write to file"},
#       {"name": "list_directory", "description": "List directory contents"},
#       {"name": "delete_file", "description": "Delete a file"}
#     ],
#     "discovered_prompts": [],
#     "discovered_resources": [],
#     "auto_approve_tools": ["read_file", "list_directory"],
#     "blocked_tools": ["delete_file", "execute_shell"],
#     "tool_risk_overrides": {"write_file": 60},
#     "created_at": "2026-01-20T10:00:00Z",
#     "created_by": "admin@company.com"
#   }
# }

Update Server Configuration

curl -X PUT https://api.ascend.security/api/registry/mcp-servers/local-file-tools \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Local File Tools (Updated)",
    "auto_approve_tools": ["read_file", "list_directory", "get_file_info"],
    "blocked_tools": ["delete_file", "delete_directory", "execute_shell"],
    "tool_risk_overrides": {
      "write_file": 65,
      "create_directory": 45,
      "move_file": 55
    }
  }'

Activate Server (Admin Required)

curl -X POST https://api.ascend.security/api/registry/mcp-servers/local-file-tools/activate \
  -H "Authorization: Bearer ADMIN_API_KEY"

# Response:
# {
#   "success": true,
#   "message": "MCP server activated: local-file-tools",
#   "server": {
#     "id": 1,
#     "server_name": "local-file-tools",
#     "is_active": true
#   }
# }

Deactivate Server

curl -X POST https://api.ascend.security/api/registry/mcp-servers/local-file-tools/deactivate \
  -H "Authorization: Bearer ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Scheduled maintenance - server upgrade"
  }'

# Response:
# {
#   "success": true,
#   "message": "MCP server deactivated: local-file-tools",
#   "server": {
#     "id": 1,
#     "server_name": "local-file-tools",
#     "is_active": false
#   },
#   "reason": "Scheduled maintenance - server upgrade"
# }

Delete Server

curl -X DELETE https://api.ascend.security/api/registry/mcp-servers/local-file-tools \
  -H "Authorization: Bearer ADMIN_API_KEY"

# Response:
# {
#   "success": true,
#   "message": "MCP server deleted: local-file-tools",
#   "deleted_by": "admin@company.com"
# }

Best Practices

Naming Conventions

Recommended Format: {purpose}-{environment}-tools

Examples:

file-system-dev-tools
database-prod-readonly-tools
code-analysis-staging-tools

Governance Configuration

Enable by Default: Always set governance_enabled: true for production
Explicit Tool Lists: Define both auto-approve and blocked tool lists
Conservative Risk Scores: Set higher risk scores initially, reduce as confidence grows

Tool Classification Strategy

┌─────────────────────────────────────────────────────────────────────────────┐
│                         TOOL CLASSIFICATION GUIDE                            │
└─────────────────────────────────────────────────────────────────────────────┘

AUTO-APPROVE (Low Risk):
├── Read-only operations
│   ├── read_file, read_directory
│   ├── get_metadata, describe_resource
│   └── list_items, search_content
└── Info queries
    ├── check_status, get_version
    └── validate_format, count_items

REQUIRE REVIEW (Medium Risk):
├── Write operations
│   ├── write_file, update_resource
│   └── create_item, modify_settings
└── Network operations
    ├── send_request, call_api
    └── upload_file, download_file

ALWAYS BLOCK (High Risk):
├── Destructive operations
│   ├── delete_file, remove_directory
│   ├── truncate_table, drop_database
│   └── terminate_process, kill_service
├── Execution operations
│   ├── execute_command, run_script
│   ├── eval_code, spawn_process
│   └── install_package, modify_system
└── Privilege operations
    ├── grant_access, revoke_permission
    ├── change_owner, modify_acl
    └── escalate_privilege

Health Monitoring

Enable Health Checks: Configure health monitoring for production servers
Alert on Degradation: Set up alerts for health status changes
Automatic Recovery: Configure reconnection attempts for transient failures
Fail Closed: Ensure governance denies calls when server is unreachable

Security Recommendations

Network Isolation: Run MCP servers in isolated network segments
Authentication: Always use authenticated connections (API keys, tokens)
TLS Encryption: Use HTTPS/WSS for remote servers
Credential Rotation: Rotate API keys and tokens regularly
Audit Logging: Enable comprehensive audit logging for all tool calls

Pre-Production Checklist

Before activating an MCP server for production:

MCP Governance Overview - MCP governance concepts
MCP Tool Governance - Tool-level policies
Agent Registry - Agent registration
Policy Management - Creating policies
Audit Logs - MCP audit trail

Compliance

MCP server registration supports compliance with:

SOC 2 CC6.1: Logical access controls
SOC 2 CC8.1: Change management for server configurations
PCI-DSS 7.1: Restrict access by business need
NIST 800-53 AC-2: Account management for MCP servers
NIST 800-53 CM-8: Information system component inventory

Overview​

Key Capabilities​

How It Works​

Registration Workflow​

Transport Types​

Server States​

Configuration​

Required Fields​

Optional Fields​

Transport Configuration​

stdio Transport​

HTTP Transport​

WebSocket Transport​

Usage Examples​

Register stdio Server (Python SDK)​

Register HTTP Server (Python SDK)​

Register MCP Server (cURL)​

List All MCP Servers​

Get Server Details​

Update Server Configuration​

Activate Server (Admin Required)​

Deactivate Server​

Delete Server​

Best Practices​

Naming Conventions​

Governance Configuration​

Tool Classification Strategy​

Health Monitoring​

Security Recommendations​

Pre-Production Checklist​

Related​

Compliance​