CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

secure-mcp-server

Secure an MCP server by applying a policy from the catalog. Handles multiple starting points: from an existing API Manager instance, from an MCP server asset in Exchange, or from scratch by publishing the MCP server first. Use when the user wants to secure an MCP server, add rate limiting, apply OAuth2, enforce IP allowlisting, or protect any MCP server with a policy — regardless of where they are in the setup process.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

SKILL.md
Quality
Evals
Security

Secure MCP Server

Overview

Applies a security or traffic management policy to an MCP server and deploys it to a self-managed Omni Gateway, walking through the full process from identifying the target MCP server to selecting a policy, configuring it, and deploying. Supports multiple starting points depending on what the user already has set up — an API Manager instance, an Exchange asset, or just an MCP server specification.

What you'll build: A fully configured policy enforced on your MCP server instance, deployed to a Omni Gateway

Architecture

sequenceDiagram
    participant User
    participant Exchange
    participant API Manager
    participant Omni Gateway
    participant Policy Catalog

    User->>Exchange: Publish MCP Server spec
    User->>Exchange: Find MCP Server asset
    Exchange-->>User: groupId, assetId, version
    User->>API Manager: Create Instance
    API Manager-->>User: instanceId
    User->>Omni Gateway: Deploy Instance
    Omni Gateway-->>User: Deployment active
    User->>Policy Catalog: Browse compatible policies
    Policy Catalog-->>User: Policy template + config schema
    User->>API Manager: Apply policy with config
    API Manager-->>Omni Gateway: Policy enforced

Prerequisites

Before starting, ensure you have:

  1. Authentication ready

    • Valid Bearer token for Anypoint Platform. If you only have username/password, call createLogin (POST /accounts/login) from the urn:api:access-management API with body {"username":"...","password":"..."} to obtain a Bearer token first.
    • API Manager permissions: View APIs Configuration and Manage Policies scopes

  2. Organization Id

    • Call listMe (GET /accounts/api/me) from urn:api:access-management to get your organization ID
    • Extract organizationId from $.user.organization.id in the response
    • This is used to list environments, browse the policy catalog, check Exchange, etc.

  3. One of the following

    • An API instance already in API Manager for the MCP server (skip to Step 3, then Step 7)
    • An MCP server asset already in Exchange (skip to Step 2)
    • An MCP server specification that needs to be published first (start at Step 1)

Choose Your Path

flowchart TD
    Start{What do you have?} -->|MCP server spec only| Full[Full Setup]
    Start -->|Asset in Exchange| FromExchange[From Exchange]
    Start -->|API Manager instance| PolicyOnly[Apply Policy Only]

    Full --> S1[Step 1: Publish to Exchange]
    S1 --> S2[Step 2: Find in Exchange]
    FromExchange --> S2
    S2 --> S3[Step 3: Select Environment]
    S3 --> S4[Step 4: Select Gateway Target]
    S4 --> S5[Step 5: Create API Instance]
    S5 --> S6[Step 6: Deploy to Gateway]

    PolicyOnly --> S3b[Step 3: Select Environment]
    S3b --> S7[Step 7: List MCP Instances]

    S6 --> S8[Step 8: Browse Policies]
    S7 --> S8

    S8 --> S9[Step 9: Apply Policy]
    S9 --> Done[✓ MCP Server Protected]

Execution Paths

This skill has multiple execution paths depending on what you already have:

  • Full setup: Steps 1, 2, 3, 4, 5, 6, 8, 9

    • When: You have an MCP server specification and need to publish it to Exchange first
    • You'll need: organizationId, MCP server specification file

  • From Exchange asset: Steps 2, 3, 4, 5, 6, 8, 9

    • When: The MCP server is already published in Exchange and you need to find it and create an API Manager instance
    • You'll need: organizationId

  • Apply policy only: Steps 3, 7, 8, 9

    • When: You already have an API Manager instance for the MCP server and want to apply a policy
    • You'll need: organizationId

Step 1: Publish MCP Server to Exchange

Publishes your MCP server specification to Exchange as a reusable asset. This makes it available for API Manager to create managed instances from it.

What you'll need:

  • Organization ID
  • MCP server specification file
  • Asset name, groupId, assetId, and version

Action: Create a new asset in Exchange with your MCP server specification.

api: urn:api:exchange-experience
operationId: uploadAsset
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Your organization's Business Group GUID
  groupId:
    userProvided: true
    description: The group ID for the asset (typically matches your organization ID)
    example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  assetId:
    userProvided: true
    description: A unique identifier for the asset in kebab-case
    example: "my-mcp-server"
  version:
    userProvided: true
    description: Semantic version for the asset
    example: "1.0.0"
outputs:
  - name: groupId
    path: $.groupId
    description: The group ID of the published asset
  - name: assetId
    path: $.assetId
    description: The asset ID of the published asset
  - name: assetVersion
    path: $.version
    description: The version of the published asset

What happens next: Your MCP server specification is now available in Exchange. Next, you can search for it to confirm and extract the coordinates needed for API Manager.

Step 2: Find MCP Server in Exchange

Search Exchange for MCP server assets. This search is not scoped to a specific organization — it returns all MCP server assets visible to the authenticated user across all organizations.

What you'll need:

  • Valid Bearer token (from Prerequisites)

Action: Search Exchange filtering by MCP asset type and select the target MCP server.

api: urn:api:exchange-experience
operationId: searchAssets
inputs:
  types:
    value: "mcp"
    description: Filter for MCP server assets only
outputs:
  - name: groupId
    path: $[*].groupId
    labels: $[*].name
    description: Group ID of the selected MCP server asset
  - name: assetId
    path: $[*].assetId
    description: Asset ID of the selected MCP server asset
  - name: assetVersion
    path: $[*].version
    description: Version of the selected MCP server asset

What happens next: You have the Exchange coordinates (groupId, assetId, version) for the MCP server. Next, select an environment where the API instance will be created.

Step 3: List Environments

List all environments in the organization so you can confirm or select the one where your MCP server instance will live.

What you'll need:

  • Organization ID

Action: List available environments and select the target.

api: urn:api:access-management
operationId: listEnvironments
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID from Prerequisites
outputs:
  - name: environmentId
    path: $.data[*].id
    labels: $.data[*].name
    description: Selected environment ID (e.g., Production, Sandbox)

What happens next: With the environment selected, you can create an API instance or browse policies.

Step 4: Select Deployment Target

List available gateway targets registered in the environment. You need the target ID and gateway version before creating the API instance, because the deployment configuration is set via a PATCH after creation.

What you'll need:

  • Organization ID and Environment ID

Action: List gateway targets and select the Omni Gateway where the MCP server will run. Prefer a target with status: "RUNNING".

api: urn:api:api-portal-xapi
operationId: getGatewayTargets
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 3
outputs:
  - name: targetId
    path: $.rows[*].id
    labels: $.rows[*].name
    description: Selected gateway target ID
  - name: targetName
    path: $.rows[*].name
    description: Name of the selected gateway target
  - name: gatewayVersion
    value: "1.0.0"
    description: Gateway version to use for deployment. The targets response may return "-" instead of a real version; use "1.0.0" as the default.

What happens next: You have a deployment target and its gateway version. Next, create the API instance and then configure its deployment target.

Step 5: Create API Manager Instance

Creates a managed API instance in API Manager from your MCP server Exchange asset. This creates the API configuration; deployment to the Omni Gateway happens in Step 6.

Important: For Omni Gateway instances, isCloudHub must be null (not false). Setting it to false causes a validation error.

What you'll need:

  • Organization ID and Environment ID
  • Exchange asset coordinates (groupId, assetId, version)

Action: Create an API instance in the target environment.

api: urn:api:api-manager
operationId: createApiInstance
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Your organization's Business Group GUID
  environmentId:
    from:
      variable: environmentId
    description: Target environment ID from Step 3
  groupId:
    from:
      variable: groupId
    description: Exchange asset group ID from Step 2
  assetId:
    from:
      variable: assetId
    description: Exchange asset ID from Step 2
  assetVersion:
    from:
      variable: assetVersion
    description: Exchange asset version from Step 2
  instanceLabel:
    userProvided: true
    description: A human-readable label for this API instance (e.g., "my-mcp-server-v1")
    example: "my-mcp-server-v1"
  technology:
    value: "flexGateway"
    description: Gateway technology — this skill targets Omni Gateway deployments
  endpoint.isCloudHub:
    value: null
    description: "Must be null for flexGateway technology (not false — false causes a validation error)"
  endpoint.proxyUri:
    userProvided: true
    description: "The proxy listener URI. Ask the user which port the Omni Gateway should listen on, then use http://0.0.0.0:<port>/"
    example: "http://0.0.0.0:8081/"
  endpoint.uri:
    userProvided: true
    optional: true
    description: The upstream backend URL for the MCP server. Ask the user if they want to provide it now or configure it later.
    example: "https://backend.example.com/mcp/v1"
outputs:
  - name: environmentApiId
    path: $.id
    description: The API instance ID in API Manager

What happens next: The API instance exists but is not yet deployed. Next, deploy it to the Omni Gateway target selected in Step 4.

Step 6: Deploy to Omni Gateway

Deploys the API instance to the selected Omni Gateway target. This uses the Proxies API deployment endpoint with flat top-level fields — do not use the nested target object, which requires additional fields that are not needed for self-managed Omni Gateway deployments.

What you'll need:

  • Organization ID, Environment ID, and API instance ID from Step 5
  • Deployment target ID and gateway version from Step 4

Action: Create a deployment for the API instance on the selected Omni Gateway.

api: urn:api:proxies-xapi
operationId: createProxyDeployment
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 3 (used in both the URL path and the request body for HY deployment type)
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 5
  type:
    value: "HY"
    description: "Deployment type for self-managed Omni Gateway (HY = Hybrid)"
  targetId:
    from:
      variable: targetId
    description: Omni Gateway target ID from Step 4
  targetName:
    from:
      variable: targetName
    description: Omni Gateway target name from Step 4
  gatewayVersion:
    value: "1.0.0"
    description: "Gateway version for deployment. Use \"1.0.0\" as the default."
  overwrite:
    value: false
    description: "Whether to overwrite an existing deployment"
outputs:
  - name: deploymentId
    path: $.id
    description: The ID of the proxy deployment

Request body structure: Use flat top-level fields, not the nested target object:

{
  "type": "HY",
  "targetId": "<from Step 4>",
  "targetName": "<from Step 4>",
  "gatewayVersion": "1.0.0",
  "environmentId": "<from Step 3>",
  "overwrite": false
}

What happens next: The MCP server instance is now deployed to the Omni Gateway. Next, browse the policy catalog to select which policy to apply.

Common issues:

  • "Field environmentId is required for deployment type HY": The environmentId must be in the request body, not just the URL path parameter.
  • "Field gatewayVersion is required for deployment type HY": Use the version from the getGatewayTargets response (Step 4). Using an incorrect version causes policy implementation errors.
  • "Policy implementations cannot be set because runtime version is unknown": The gatewayVersion value doesn't match a known Omni Gateway version. Verify the version from the target's actual runtime version in Step 4.
  • 409 Conflict: The MCP server may already be deployed to this target. List existing deployments with GET .../deployments first to check.

Step 7: List MCP Server Instances

Lists MCP server instances in the selected environment by filtering with family=agentic. Use this step when you already have an API Manager instance for the MCP server and need to find its ID to apply a policy.

What you'll need:

  • Organization ID and Environment ID

Action: List MCP server instances and select the target.

api: urn:api:api-manager
operationId: listApiInstances
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 3
  family:
    value: "agentic"
    description: Filter for MCP server (agentic) instances only
outputs:
  - name: environmentApiId
    path: $.assets[*].apis[*].id
    labels: $.assets[*].apis[*].autodiscoveryInstanceName
    description: The MCP server instance ID in API Manager

What happens next: You have the MCP server instance ID. Next, browse the policy catalog to select which policy to apply.

Step 8: Browse Exchange Policy Catalog

List all available policy templates from Exchange for your organization. This endpoint returns the full Exchange coordinates (groupId, assetId, assetVersion) and gateway-compatible configuration for each template — these are required when applying a policy.

Important: Use the api-portal-xapi endpoint (getExchangePolicyTemplates) instead of the generic listPolicyTemplates endpoint. The generic endpoint does not return Exchange coordinates or gateway-specific configuration property names, which are required for the apply step.

What you'll need:

  • Organization ID
  • Environment ID and API instance ID (to filter for compatible templates)

Action: List Exchange policy templates and select the one to apply. Pass apiInstanceId and environmentId to filter for templates compatible with your MCP server's gateway type (e.g., Omni Gateway, Mule Gateway).

api: urn:api:api-portal-xapi
operationId: getExchangePolicyTemplates
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  apiInstanceId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 5 or Step 7 (filters for compatible templates)
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 3
  latest:
    value: "true"
    description: Return only the latest version of each template
  includeConfiguration:
    value: "true"
    description: Include the configuration schema for each template
outputs:
  - name: policyGroupId
    path: $[*].groupId
    labels: $[*].assetId
    description: Exchange group ID of the selected policy template
  - name: policyAssetId
    path: $[*].assetId
    description: Exchange asset ID of the selected policy template
  - name: policyAssetVersion
    path: $[*].version
    description: Exchange version of the selected policy template (gateway-compatible)
  - name: policyConfiguration
    path: $[*].configuration
    description: Configuration schema with gateway-compatible property names and defaults

What happens next: You have the policy template's Exchange coordinates and its configuration schema with the correct property names for your gateway type. Review the policyConfiguration output to understand what settings the policy accepts before applying it.

Common issues:

  • Empty list: Pass apiInstanceId and environmentId to get templates compatible with your gateway type. Without these filters, some templates may not appear.
  • Wrong config property names: Always use the configuration from this endpoint — the generic listPolicyTemplates endpoint may return different (non-gateway-compatible) property names and defaults.

Step 9: Apply Policy to API Instance

Apply the selected policy to your MCP server instance with the appropriate configuration. Use the Exchange coordinates and configuration property names from Step 8.

What you'll need:

  • Organization ID, Environment ID, and API instance ID
  • Policy Exchange coordinates (groupId, assetId, assetVersion) from Step 8
  • Policy configuration based on the schema from Step 8's policyConfiguration output

Action: Apply the policy to your API instance. Build the configurationData object using the property names from Step 8's configuration schema. For each configuration property, present the user with the property name, its description, and the default value, then ask if they want to keep the default or provide a custom value. If a property has no default, always ask the user for a value.

api: urn:api:api-manager
operationId: applyApiInstancePolicy
inputs:
  organizationId:
    from:
      api: urn:api:access-management
      operation: listMe
      field: $.user.organization.id
    description: Organization ID
  environmentId:
    from:
      variable: environmentId
    description: Environment ID from Step 3
  environmentApiId:
    from:
      variable: environmentApiId
    description: API instance ID from Step 5 or Step 7 (or provided manually)
  groupId:
    from:
      variable: policyGroupId
    description: Policy Exchange group ID from Step 8
  assetId:
    from:
      variable: policyAssetId
    description: Policy Exchange asset ID from Step 8
  assetVersion:
    from:
      variable: policyAssetVersion
    description: Policy Exchange version from Step 8
outputs:
  - name: policyId
    path: $.id
    description: The ID of the applied policy instance

What happens next: Your MCP server is now protected with the selected policy. Since the API instance was configured with deployment information in Step 6, the policy is active and enforcing on the Omni Gateway.

Common issues:

  • 400 Bad Request — missing groupId/assetId/assetVersion: The apply endpoint requires full Exchange coordinates, not just a template ID. Make sure you used getExchangePolicyTemplates (Step 8) to get these values.
  • 400 Bad Request — invalid configurationData: The configuration property names differ between gateway types. Use the property names from Step 8's policyConfiguration output, not from the generic template endpoint. For example, Omni Gateway uses credentialsOriginHasHttpBasicAuthenticationHeader while the generic template uses credentialsOrigin.
  • 409 Conflict: A policy of this type may already be applied to the API instance. List existing policies first to check, or add ?allowDuplicated=true to the request URL to apply a second instance of the same policy type.
  • 403 Forbidden: You need Manage Policies permission in the target environment.

Completion Checklist

After completing all steps, verify:

  • MCP server instance is bound to the Omni Gateway target (deployment info visible in API Manager)
  • Policy appears in the API instance's policy list
  • Policy status shows as "Active"
  • MCP server requests are being evaluated against the policy rules
  • Policy configuration matches your requirements

What You've Built

Your MCP server is now protected with:

  • Policy enforcement — Selected policy is active on your MCP server instance. All incoming traffic is evaluated against policy rules.
  • Bound to Omni Gateway — API instance is created with deployment configuration targeting a self-managed Omni Gateway. The Omni Gateway picks up the configuration automatically.
  • Managed configuration — Policy settings are version-controlled in API Manager. Configuration can be updated without redeploying the MCP server.

Next Steps

  1. Test the policy

    • Send test requests to verify the policy is enforcing correctly
    • Check that authorized requests pass and unauthorized ones are blocked

  2. Add more policies

    • Run this skill again to layer additional policies (e.g., rate limiting + OAuth2)
    • Policy ordering matters — adjust priority in API Manager if needed

  3. Monitor policy activity

    • Check API Manager analytics for policy enforcement metrics
    • Set up alerts for unusual rejection patterns

Tips and Best Practices

Policy Selection

  • Rate Limiting: Use when you need to control traffic volume per client
  • OAuth 2.0: Use for token-based authentication and authorization
  • IP Allowlist/Blocklist: Use to restrict access by network origin
  • Client ID Enforcement: Use to require registered client applications

Policy Ordering

  • Authentication policies should be applied first (lowest order number)
  • Rate limiting should come after authentication
  • Transformation policies should be last

Gateway Compatibility

  • Always use getExchangePolicyTemplates with apiInstanceId to get gateway-compatible templates
  • Configuration property names and defaults vary by gateway type (Omni Gateway vs. Mule Gateway)
  • The Exchange template version may differ from the generic template version

MCP Server Discovery

  • The Exchange search in Step 2 is not org-scoped — it returns all MCP servers visible to the authenticated user
  • Use the asset name field to identify the correct MCP server when multiple results are returned
  • If you published the MCP server in Step 1, its coordinates are already available — Step 2 can be used to confirm

Troubleshooting

Policy Not Enforcing

Symptoms: Requests pass through without policy evaluation

Possible causes:

  • API instance is not deployed or is in an error state
  • Policy configuration has a permissive default that allows all traffic
  • Policy is applied but not yet propagated (wait 1-2 minutes)

Solutions:

  • Check API instance status in API Manager
  • Review policy configuration for overly permissive settings
  • Wait for propagation and retry

Policy Blocks All Requests

Symptoms: All requests return 401 or 403, even legitimate ones

Possible causes:

  • Policy configuration is too restrictive
  • Required credentials are not being sent correctly
  • Policy expects headers or parameters in a specific format

Solutions:

  • Review the policy configuration schema for required fields
  • Check that client applications are sending credentials in the expected format
  • Temporarily disable the policy to isolate the issue

400 Error When Applying Policy

Symptoms: "The policy to be created is missing at least one of the following properties related to the policy template: 'groupId', 'assetId', 'assetVersion'."

Possible causes:

  • Used the generic listPolicyTemplates endpoint which does not return Exchange coordinates

Solutions:

  • Use getExchangePolicyTemplates from api-portal-xapi instead — this returns the full Exchange coordinates needed by the apply endpoint

MCP Server Not Found in Exchange

Symptoms: Step 2 returns an empty list

Possible causes:

  • The MCP server has not been published to Exchange yet
  • The asset type is not mcp

Solutions:

  • Start from Step 1 to publish the MCP server to Exchange first
  • Verify the asset was published with the correct type

Related Jobs

  • secure-api: The equivalent skill for securing standard APIs with policies
  • apply-policy-to-api-instance: Apply a policy when you already have an API instance (simpler flow)
Repository

mulesoft/mulesoft-dx

Path

skills/secure-mcp-server/SKILL.md

Revision

4340d6c

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill