---
title: Create MCP policies for PingGateway
description: Create Advanced Identity Cloud resource types, policy sets, and policies for Model Context Protocol (MCP) requests that PingGateway evaluates with Advanced Identity Cloud, including the resource and action contract and wildcard matching rules.
component: pingoneaic
page_id: pingoneaic:am-authorization:mcp-policy-authorization
canonical_url: https://docs.pingidentity.com/pingoneaic/am-authorization/mcp-policy-authorization.html
llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Authorization", "Policy", "MCP", "AI agents", "PingGateway", "REST API"]
page_aliases: ["authorization-guide:mcp-policy-authorization.adoc"]
section_ids:
  how_it_works: How it works
  mcp-resource-action-contract: The MCP resource and action contract
  mcp-policy-authorization-prerequisites: Before you begin
  mcp-policy-authorization-resource-type: Create the MCP resource type
  create_the_resource_type_in_the_advanced_identity_cloud_admin_console: Create the resource type in the Advanced Identity Cloud admin console
  create_the_resource_type_over_rest: Create the resource type over REST
  mcp-policy-authorization-policy-set: Create the policy set
  create_the_policy_set_in_the_ui: Create the policy set in the UI
  create_the_policy_set_over_rest: Create the policy set over REST
  mcp-policy-authorization-policies: Create MCP policies
  create_the_policy_in_the_ui: Create the policy in the UI
  create_the_policy_over_rest: Create the policy over REST
  mcp-policy-authorization-wildcards: Wildcard matching for MCP resources
  mcp-policy-authorization-test: Test MCP policy decisions
  resource_covered_by_a_policy: Resource covered by a policy
  resource_not_covered_by_a_policy: Resource not covered by a policy
  connect_pinggateway_to_the_policy_evaluation: Connect PingGateway to the policy evaluation
  mcp-policy-authorization-troubleshooting: Troubleshoot failed policy matches
---

# Create MCP policies for PingGateway

A Model Context Protocol (MCP) server can expose tools and resources for [AI agents](../identity-for-ai/ai-agent-identities.html) to use. In a production deployment, system administrators typically need to control which authenticated agents can use which tools and access which resources. For example, one agent might be allowed to call a location service, while another might be allowed only to read specific data. You can create MCP policies, policy sets, and resource types to control such agent permissions.

## How it works

PingGateway protects MCP traffic by asking Advanced Identity Cloud to decide whether an agent is allowed to perform each requested operation. PingGateway acts as the [policy enforcement point (PEP)](https://docs.pingidentity.com/pinggateway/latest/gateway-guide/policy-enforcement.html): it sends the request details to Advanced Identity Cloud, receives the authorization decision, and allows or blocks the request before it reaches the MCP server. Advanced Identity Cloud acts as the [policy decision point (PDP)](what-is-authz-decision.html): it evaluates the request against the configured policies.

![Flow of an MCP request from the AI agent through PingGateway and Advanced Identity Cloud to the MCP server, and the allow and deny outcomes](_images/mcp-policy-flow.svg)

The AI agent, acting as the MCP client, sends a JSON-RPC message to the MCP server through PingGateway. PingGateway then derives a single Advanced Identity Cloud resource and action from the message. Advanced Identity Cloud takes no part in the JSON-RPC exchange.

Each message contains a `method` that names the requested operation, and parameters that specify the object the operation targets. For example, this message asks the MCP server to call its `geocode` tool:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "geocode",
    "arguments": { "location": "Paris" }
  }
}
```

PingGateway derives the resource / action pair from the message:

* The method, `tools/call`, becomes the Advanced Identity Cloud action.

* The target object, the `geocode` tool, becomes the Advanced Identity Cloud resource `tool/geocode`.

Each MCP method maps to one resource / action pair, as shown in the [contract table](#mcp-resource-action-contract). For an allow decision, Advanced Identity Cloud needs a policy whose resource patterns match the request's resource and whose action values include the request's action.

Advanced Identity Cloud policies must use values that match the resource / action pair PingGateway derives. The resource can match exactly or through an intentional pattern such as `tool/*`; the action must match the requested action. Advanced Identity Cloud doesn't provide default MCP resource types or policies for these values, so you have to create them. These values are the PingGateway MCP integration convention; other enforcement points can derive different values.

Advanced Identity Cloud authorization uses three objects, which you create in this order:

* A [*resource type*](#mcp-policy-authorization-resource-type) defines the resource patterns and the actions that policies can use. For MCP, it lists the pattern and action families that PingGateway sends.

* A [*policy set*](#mcp-policy-authorization-policy-set) groups policies and binds them to one or more resource types. When PingGateway requests a decision, it names the policy set it uses.

* A [*policy*](#mcp-policy-authorization-policies) grants a subject permission to perform an action on a resource, using the patterns and actions its resource type defines.

This page explains how to create each one for the MCP integration.

|   |                                                                                                                                                                                       |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | Learn more about the PingGateway side of the integration in [MCP security gateway](https://docs.pingidentity.com/pinggateway/latest/mcp/index.html) in the PingGateway documentation. |

## The MCP resource and action contract

The contract is the requirement that Advanced Identity Cloud policies match the set of values PingGateway derives and sends for each MCP JSON-RPC message. The following table lists the values per method:

| MCP method                                                      | Resource               | Action                                   |
| --------------------------------------------------------------- | ---------------------- | ---------------------------------------- |
| `tools/call`                                                    | `tool/name`            | `tools/call`                             |
| `resources/read`                                                | `resource/uri`         | `resources/read`                         |
| `resources/subscribe`                                           | `resource/uri`         | `resources/subscribe`                    |
| `resources/unsubscribe`                                         | `resource/uri`         | `resources/unsubscribe`                  |
| `prompts/get`                                                   | `prompt/name`          | `prompts/get`                            |
| `tasks/get`                                                     | `task/taskId`          | `tasks/get`                              |
| `tasks/result`                                                  | `task/taskId`          | `tasks/result`                           |
| `tasks/cancel`                                                  | `task/taskId`          | `tasks/cancel`                           |
| `completion/complete` for a prompt reference                    | `prompt/name`          | `completion/complete`                    |
| `completion/complete` for a resource reference                  | `resource/uri`         | `completion/complete`                    |
| `tools/list`                                                    | `tools`                | `tools/list`                             |
| `resources/list`                                                | `resources`            | `resources/list`                         |
| `resources/templates/list`                                      | `resources/templates`  | `resources/templates/list`               |
| `prompts/list`                                                  | `prompts`              | `prompts/list`                           |
| `tasks/list`                                                    | `tasks`                | `tasks/list`                             |
| `initialize`, `ping`, `logging/setLevel`, and `notifications/*` | No resource is derived | Not evaluated by Advanced Identity Cloud |

Key points:

* The action is always the MCP method name, exactly as the request carries it, including the `/` character.

* Methods that list what the server exposes, such as `tools/list` and `resources/list`, target the collection of objects rather than a specific object. Their resource is the category name, such as `tools` or `resources`, instead of an individual item.

* A `completion/complete` request asks the server for argument suggestions. Its resource depends on what the request references: `prompt/name` for a prompt's arguments, or `resource/uri` for a resource URI.

* Requests to the session methods `initialize`, `ping`, and `logging/setLevel`, and to notifications such as `notifications/initialized`, don't touch a protected object, so they don't produce a policy decision. The PEP shouldn't request policy decisions for them, so your policies don't need to cover them.

* Both the resource and the action must match for Advanced Identity Cloud to make a policy decision. For example, an action for one MCP resource family, such as `tools/call`, doesn't authorize an unrelated family, such as `resource/weather://latest`.

You use the values in this table to create the resource type, policy set, and policies in the following sections.

## Before you begin

Before authoring MCP policies, make sure you have the following:

* A configured Advanced Identity Cloud realm, such as `alpha`, where you can manage authorization objects.

* A user with the privileges to manage resource types, policy sets, and policies in that realm.

* A test subject and its single sign-on (SSO) token, to verify policy decisions over REST.

## Create the MCP resource type

Create a custom [resource type](configuring-resource-types.html) that lists the resource patterns and actions your deployment needs.

Apply the principle of least privilege when you choose the resource type's patterns and actions:

* Add a pattern family only when the MCP server exposes those objects, such as `prompt/*` only for a server that offers prompts.

* Add an action only for an MCP method you intend to authorize.

* For a server that exposes only tools, a resource type with the single pattern `tool/*` and the single action `tools/call` can be enough.

Whatever patterns and actions you choose, make sure they come from the same family or families. A resource type with the pattern `resource/*` and only the action `tools/call` can never grant access, because no request produces `tools/call` on a resource value that `resource/*` matches. The full example later in this section covers several families and works because every action it includes has a matching pattern from its own family.

### Create the resource type in the Advanced Identity Cloud admin console

1. Under Native Consoles > Access Management, go to Realms > *realm name* > Authorization > Resource Types.

2. Click New Resource Type.

3. Enter a name, such as `MCP`.

4. Under Specify Patterns, enter each pattern your MCP server needs, such as `tool/*` or `resource/*`, then click Add Pattern.

5. Under Specify Actions, enter the lowercase MCP method name for each action your deployment authorizes, such as `tools/call`, then click + Add Action.

   For each action, set the default state to Allow. The policies in this page allow the actions they match, so the resource type must allow them by default.

6. Save your changes.

|   |                                                                                                                                                                                                                                                                                                                                                                                            |
| - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|   | Action values, such as `tools/call`, must be all lowercase to match the corresponding MCP message method name. If an action value has an uppercase letter it won't match the method name and the policy won't work. The Advanced Identity Cloud admin console displays action names in uppercase after you save, but the stored and evaluated value has the case used when it was entered. |

### Create the resource type over REST

To create the resource type:

1. Authenticate as [a user with the privileges required to manage resource types](rest-api-authz-resource-types.html#access_the_endpoints).

2. Send a `POST` request to the `resourcetypes` endpoint.

   |   |                                                                                                                                                                      |
   | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | The following example includes every pattern and action from the contract table. In your `POST` request, include only the patterns and actions your deployment uses. |

   ```bash
   $ curl \
   --request POST \
   --header "Content-Type: application/json" \
   --header "<session-cookie-name>: <policy-admin-tokenId>" \
   --header "Accept-API-Version: resource=1.0" \
   --data '{
     "name": "MCP",
     "description": "MCP resources and actions for PingGateway policy evaluation",
     "patterns": ["tool/*", "resource/*", "prompt/*", "task/*", "tools", "resources", "resources/templates", "prompts", "tasks"],
     "actions": {
       "tools/call": true,
       "tools/list": true,
       "resources/read": true,
       "resources/subscribe": true,
       "resources/unsubscribe": true,
       "resources/list": true,
       "resources/templates/list": true,
       "prompts/get": true,
       "prompts/list": true,
       "tasks/get": true,
       "tasks/result": true,
       "tasks/cancel": true,
       "tasks/list": true,
       "completion/complete": true
     }
   }' \
   'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/resourcetypes/?_action=create'
   {
     "_id": "5ec8a3f2-9b41-4c7d-a2e6-18f0d4b7c931",
     "uuid": "5ec8a3f2-9b41-4c7d-a2e6-18f0d4b7c931",
     "name": "MCP",
     "description": "MCP resources and actions for PingGateway policy evaluation",
     "patterns": ["tool/", "resource/", "prompt/", "task/", "tools", "resources", "resources/templates", "prompts", "tasks"],
     "actions": {
       "tools/call": true,
       "tools/list": true,
       "resources/read": true,
       "resources/subscribe": true,
       "resources/unsubscribe": true,
       "resources/list": true,
       "resources/templates/list": true,
       "prompts/get": true,
       "prompts/list": true,
       "tasks/get": true,
       "tasks/result": true,
       "tasks/cancel": true,
       "tasks/list": true,
       "completion/complete": true
     },
     "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
     "creationDate": 1767139200000,
     "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
     "lastModifiedDate": 1767139200000
   }
   ```

3. Record the `uuid` field of the response. The policy set and the policies reference it.

Learn more about [resource types](configuring-resource-types.html), and about [managing them over REST](rest-api-authz-resource-types.html).

## Create the policy set

Create a [policy set](configuring-policy-sets.html) that references the resource type by its UUID, and record the policy set name. When PingGateway requests a decision, it sends the policy set name in the `application` property, and Advanced Identity Cloud evaluates the policies in that set. Each policy set protects one MCP server, so name the set for the server it protects, such as `mcpPolicySet`.

Make sure the policy set:

* Belongs to the realm that you will configure in the PingGateway `PolicyEnforcementFilter` for policy evaluation.

* Has a name that you will use as the `application` property in the `PolicyEnforcementFilter` configuration.

* Uses the `iPlanetAMWebAgentService` application type, which compares resource values with the URL resource name comparator. Learn more in [Wildcard matching for MCP resources](#mcp-policy-authorization-wildcards).

### Create the policy set in the UI

1. Under Native Consoles > Access Management, go to Realms > *realm name* > Authorization > Policy Sets.

2. Click + New Policy Set.

3. Enter an ID, such as `mcpPolicySet`.

   The ID is the policy set's unique name in the REST API, and the value that the `application` property of the `PolicyEnforcementFilter` refers to. You can't change the ID after creating the policy set.

4. Enter a name.

   The **Name** field is a display label and isn't used for matching.

5. Select the `MCP` resource type.

6. Save your changes.

### Create the policy set over REST

To create the policy set, send a `POST` request to the `applications` endpoint:

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <policy-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "mcpPolicySet",
  "applicationType": "iPlanetAMWebAgentService",
  "resourceTypeUuids": ["<resource-type-uuid>"],
  "realm": "/alpha"
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/applications/?_action=create'
{
  "_id": "mcpPolicySet",
  "_rev": "1767139200000",
  "name": "mcpPolicySet",
  "description": null,
  "attributeNames": [],
  "resourceTypeUuids": ["5ec8a3f2-9b41-4c7d-a2e6-18f0d4b7c931"],
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "conditions": ["Script", "AMIdentityMembership", "IPv6", "IPv4", "SimpleTime", "LEAuthLevel", "LDAPFilter", "AuthScheme", "Session", "AND", "AuthenticateToRealm", "ResourceEnvIP", "Policy", "OAuth2Scope", "SessionProperty", "OR", "Transaction", "NOT", "AuthLevel", "AuthenticateToService"],
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": 1767139200000,
  "lastModifiedDate": 1767139200000,
  "subjects": ["AuthenticatedUsers", "NOT", "Identity", "OR", "AND", "NONE", "Policy", "JwtClaim"],
  "saveIndex": null,
  "searchIndex": null,
  "entitlementCombiner": "DenyOverride",
  "resourceComparator": null,
  "editable": true,
  "applicationType": "iPlanetAMWebAgentService",
  "actions": {
    "HEAD": true,
    "DELETE": true,
    "POST": true,
    "GET": true,
    "OPTIONS": true,
    "PUT": true,
    "PATCH": true
  },
  "resources": ["*://*:*/*", "*://*:*/*?*"],
  "realm": "/alpha"
}
```

The `resourceTypeUuids` field references the resource type by `<resource-type-uuid>`, the UUID you recorded when you created the resource type.

Learn more about [policy sets](configuring-policy-sets.html), and about [managing them over REST](rest-api-authz-applications.html).

## Create MCP policies

When creating policies, follow these guidelines:

* You must use the exact resource and action values listed in the [contract table](#mcp-resource-action-contract). Action values are case-sensitive; resource values aren't.

* For a policy to work, it must include the resource and action of the requests you want it to allow.

* Only use wildcard resources when necessary. A policy for `resource/*` allows the action on every MCP resource the server exposes. Learn more in [Wildcard matching for MCP resources](#mcp-policy-authorization-wildcards).

* Choose subjects, environments, and conditions that fit your deployment. Learn more in [Conditions](policies-ui.html#conditions).

|   |                                                                                                                                                                                                                               |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | The `AuthenticatedUsers` subject in the following examples applies the policy to any authenticated user. It's suitable for demonstration only. For production, restrict the subject to specific users, groups, or conditions. |

### Create the policy in the UI

1. Under Native Consoles > Access Management, go to Realms > *realm name* > Authorization > Policy Sets and select `mcpPolicySet`.

2. Click Add a Policy.

3. Enter a name, such as `call-geocode-tool`.

4. Select the `MCP` resource type.

5. On the Resources tab, specify the resource the policy covers, such as `tool/geocode`.

6. On the Actions tab, select the action from the [contract table](#mcp-resource-action-contract), such as `tools/call`.

7. On the Subjects tab, choose the subject that fits your deployment.

8. Click Create.

### Create the policy over REST

The following example policy allows the `tools/call` action on the `tool/geocode` resource:

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <policy-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "call-geocode-tool",
  "active": true,
  "description": "Allow MCP clients to call the geocode tool",
  "applicationName": "mcpPolicySet",
  "resourceTypeUuid": "<resource-type-uuid>",
  "resources": ["tool/geocode"],
  "actionValues": {
    "tools/call": true
  },
  "subject": {
    "type": "AuthenticatedUsers"
  }
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies/?_action=create'
{
  "_id": "call-geocode-tool",
  "_rev": "1767139200000",
  "name": "call-geocode-tool",
  "active": true,
  "description": "Allow MCP clients to call the geocode tool",
  "resources": ["tool/geocode"],
  "applicationName": "mcpPolicySet",
  "actionValues": {
    "tools/call": true
  },
  "subject": {
    "type": "AuthenticatedUsers"
  },
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": "2026-10-30T12:00:00.000Z",
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": "2026-10-30T12:00:00.000Z"
}
```

The second example policy allows the `resources/read` action on the `resource/weather://latest` resource:

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <policy-admin-tokenId>" \
--header "Accept-API-Version: resource=1.0" \
--data '{
  "name": "read-latest-weather-resource",
  "active": true,
  "description": "Allow MCP clients to read the latest weather resource",
  "applicationName": "mcpPolicySet",
  "resourceTypeUuid": "<resource-type-uuid>",
  "resources": ["resource/weather://latest"],
  "actionValues": {
    "resources/read": true
  },
  "subject": {
    "type": "AuthenticatedUsers"
  }
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies/?_action=create'
{
  "_id": "read-latest-weather-resource",
  "_rev": "1767139200000",
  "name": "read-latest-weather-resource",
  "active": true,
  "description": "Allow MCP clients to read the latest weather resource",
  "resources": ["resource/weather://latest"],
  "applicationName": "mcpPolicySet",
  "actionValues": {
    "resources/read": true
  },
  "subject": {
    "type": "AuthenticatedUsers"
  },
  "lastModifiedBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "lastModifiedDate": "2026-10-30T12:00:00.000Z",
  "createdBy": "id=1dff18dc-ac57-4388-8127-dff309f80002,ou=user,o=alpha,ou=services,ou=am-config",
  "creationDate": "2026-10-30T12:00:00.000Z"
}
```

## Wildcard matching for MCP resources

When PingGateway requests a decision on whether an agent is allowed to perform an operation, Advanced Identity Cloud matches the request's resource against the policy's resource patterns. A pattern can match a single resource exactly, or use wildcards to match a set of resources. For example, the pattern `tool/*` matches every tool resource the server exposes, such as `tool/geocode`.

Policy sets with the application type `iPlanetAMWebAgentService` compare resource values with the URL resource name comparator, so the delimiter is `/` and matching isn't case-sensitive by default.

Two wildcards are available:

* `*`

  The multi-level wildcard. It matches across `/` delimiters, including nested segments.

* `-*-`

  The one-level wildcard. It matches a single segment and doesn't cross a `/` delimiter.

The following examples show how patterns match MCP resources:

| Pattern        | Matches                                                                  | Description                                                                                                        |
| -------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `resource/*`   | `resource/weather://latest`, including URIs with additional `/` segments | Matches every resource URI the server exposes. Use this multi-level wildcard for URI resources.                    |
| `tool/*`       | `tool/geocode` and nested tool names, such as `tool/map/geocode`         | Covers the whole tool family. Use a specific tool resource for least privilege.                                    |
| `resource/-*-` | A single level after `resource/`, such as `resource/latest`              | Matches one segment only. Doesn't match `resource/weather://latest` when the URI contains additional `/` segments. |
| `tool/Geocode` | `tool/geocode` and `tool/GEOCODE`                                        | Matching isn't case-sensitive, so don't rely on letter case to separate resources.                                 |

To change the delimiters, the wildcards, or case sensitivity for policy sets, edit the resource comparator in the global policy configuration. Learn more in [Resource type patterns](resource-types-ui.html#policy-patterns-wildcards).

## Test MCP policy decisions

You can test your policies by requesting decisions from Advanced Identity Cloud yourself before you connect PingGateway. PingGateway sends the same request automatically when it protects MCP traffic, so a decision that works here works in the integration.

The following examples use `mcpPolicySet` as the policy set and the weather policy from the previous sections.

To evaluate the weather resource:

1. [Authenticate](../am-authentication/login-using-rest.html) as the system administrator to obtain the administrator's session token.

2. Authenticate as the test subject to obtain the test subject's SSO token.

   The evaluation requires both: the session token in the `<session-cookie-name>` header authorizes the request, and the subject's SSO token in the body is the subject the decision is for. Learn more in [Session tokens after authentication](../am-authentication/rest-using-ssotokens.html).

3. Put the policy set name in the `application` field, and the subject token in the body.

4. Send a `POST` request to the `policies` endpoint with the `evaluate` action.

### Resource covered by a policy

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <policy-admin-tokenId>" \
--header "Accept-API-Version: resource=2.1" \
--data '{
  "resources": ["resource/weather://latest"],
  "application": "mcpPolicySet",
  "subject": {
    "ssoToken": "<subject-tokenId>"
  }
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies?_action=evaluate'
```

The matching policy allows the requested action. Advanced Identity Cloud returns the decision for the resource, with the action's value set to `true` to indicate the action is allowed:

```json
[{
    "resource": "resource/weather://latest",
    "actions": {
        "resources/read": true
    },
    "attributes": {},
    "advices": {}
}]
```

### Resource not covered by a policy

```bash
$ curl \
--request POST \
--header "Content-Type: application/json" \
--header "<session-cookie-name>: <policy-admin-tokenId>" \
--header "Accept-API-Version: resource=2.1" \
--data '{
  "resources": ["prompt/translate"],
  "application": "mcpPolicySet",
  "subject": {
    "ssoToken": "<subject-tokenId>"
  }
}' \
'https://<tenant-env-fqdn>/am/json/realms/root/realms/alpha/policies?_action=evaluate'
```

No policy matches `prompt/translate`, so the decision contains no actions. The empty `actions` field indicates that no action is allowed:

```json
[{
    "resource": "prompt/translate",
    "actions": {},
    "attributes": {},
    "advices": {}
}]
```

An action that's absent from the `actions` field, or that appears as `false`, isn't authorized. Treat such a decision as a denial. The exact response PingGateway sends to the MCP client depends on its configuration.

Learn more about the evaluation payload and the response in [Request policy decisions over REST](rest-api-authz-policy-decisions.html).

## Connect PingGateway to the policy evaluation

When your policies return the decisions you expect, configure your PingGateway `PolicyEnforcementFilter` to protect MCP traffic with the policy set name in the `application` property and an `amService` for Advanced Identity Cloud. Learn more in [Policy enforcement](https://docs.pingidentity.com/pinggateway/latest/gateway-guide/policy-enforcement.html) in the PingGateway documentation.

## Troubleshoot failed policy matches

Failed policy matches produce empty decision responses and denials from PingGateway. The following items describe the common causes and the display behavior that helps you diagnose them:

* The request's action doesn't match the policy's actions

  Action matching is case-sensitive; confirm that the policy's action values are the lowercase MCP method names, such as `resources/read`. The Advanced Identity Cloud admin console displays action names in uppercase even when the entered value is lowercase.

* The request's resource doesn't match the policy's resources

  Compare the resource and action values PingGateway sends with the values in [the MCP resource and action contract](#mcp-resource-action-contract). Resource matching ignores case, but the values must otherwise match exactly.

* The request's resource is a URI the policy's pattern doesn't cover

  Use the multi-level wildcard `resource/*` for URI resources. The one-level wildcard `-*-` matches a single segment only, so it doesn't match URIs that contain `/`. See [Wildcard matching for MCP resources](#mcp-policy-authorization-wildcards).

* The decision response contains no actions, or PingGateway returns unexpected denials

  Confirm that the policy set name in the `application` field matches the policy set exactly, and that the filter's realm matches the realm that contains the policy set. Also check the resource type UUID on the policy set, and the policy's resources, actions, realm, and subject. See [Request policy decisions over REST](rest-api-authz-policy-decisions.html).

* PingGateway requests decisions for MCP methods that policies don't cover

  When the PingGateway `PolicyEnforcementFilter` handles MCP requests that the policy evaluation doesn't need, such as `initialize`, `ping`, or `notifications/*`, it requests unnecessary decisions and can deny the requests. Configure the route to bypass the `PolicyEnforcementFilter` for those methods. Learn more in [Policy enforcement](https://docs.pingidentity.com/pinggateway/latest/gateway-guide/policy-enforcement.html) in the PingGateway documentation.
