What is Mcp Authentication Demo

mcp-authentication-demo is a demonstration project that showcases how to manage access control for Model Context Protocol (MCP) servers using Amazon Verified Permissions (AVP) and OAuth2-based authentication with Cognito.

Use cases

Use cases for mcp-authentication-demo include scenarios where multiple agentic applications interact with an MCP server, requiring different access levels for different applications, such as fetching or updating customer data based on user roles or regions.

How to use

To use mcp-authentication-demo, set up the necessary AWS services, including Amazon Cognito for user authentication and AVP for access control. Then, connect your client applications to the MCP server, ensuring that access tokens are configured with the appropriate scopes.

Key features

Key features of mcp-authentication-demo include OAuth scope-based client access control, tool-level access checks, and user-level data access management based on Cognito identity and IAM role mapping.

Where to use

mcp-authentication-demo can be used in enterprise environments where backend systems like CRM, ERP, or fulfillment platforms expose services through MCP servers, and where different client applications need controlled access to these services.

🔐 MCP Authorization Demo using Amazon Verified Permissions

This repo shows how to control access to Model Context Protocol (MCP) servers using Amazon Verified Permissions (AVP) and OAuth2-based authentication with Cognito.

It’s a working example where different clients (agentic apps) connect to an MCP server, but each client only gets access to the tools it’s allowed to use. That control comes from scopes in their access token and policies defined in AVP.

🧭 Why this demo?

In enterprise settings, teams responsible for backend systems (like CRM, ERP, or fulfillment platforms) may expose their services via MCP servers, while separate teams build agentic applications that interact with them.

Take a CRM system as an example:

• The CRM team exposes tools (like get customer, update customer) through an MCP server.
• Different agent apps connect to that server — some might just fetch data, others might also update it.

Here’s where access control becomes important:

• You want to control which client apps can connect to your MCP server.
• And for those that can connect, you want to limit which tools they can use.
• On top of that, once a human user logs into the agent app, they should only see the data they’re allowed to access — for example, based on their region or role.

This demo shows how to do all that:

• Client access is controlled using OAuth scopes and AVP.
• Tool-level access is checked before sending the list of tools.
• User-level data access is based on Cognito identity + IAM role mapping.

🧠 What is MCP?

MCP is a protocol for making AI apps (like LLM agents) work better with tools and external systems. It gives you a standard way for:

• Discovering what tools are available
• Letting agents send tool calls (based on natural language intent)
• RInteract with tools via structured input/output

⚙️ How this works (high level)

+------------------+                     +-------------------+                     +-------------------------------+
|   Agent Client   |  -- client token -->|     MCP Server     | -- authorize -->   | Amazon Verified Permissions   |
|                  |  -- user token ---->|                   | -- context+scope -->| (Policy Store + Cognito)      |
+------------------+                     +-------------------+                     +-------------------------------+
      |                                          |
      |----------- listTools ------------------->| (scopes filtered via AVP)
      |<---------- allowed tools ----------------|
      |----------- callTool(tool) -------------->| (user ID token → AWS credentials)

📁 Project Structure

This repo has both client and server:

.
├── client/                          # Next.js app with Amplify Gen2
│   ├── amplify/                     # Amplify backend setup
│   ├── amplify.yaml                 # Build settings for Amplify
│   ├── config/                      # Environment configs
│   │   └── index.ts
│   └── amplify_outputs.json         # Cognito values after deploy
├── server/                          # MCP server with auth logic
│   └── src/
│       └── config/
│           └── config.ts

⚠️ Manual Setup Requirements

This demo provisions Cognito resources using Amplify Gen2. However, you must manually configure:

• Cognito user groups (optional, based on use case)
• IAM roles for authenticated users
• Cognito Identity Pool role mappings
• Amazon Verified Permissions (AVP) policy store, schema, and policies

🔧 Setup (Step-by-step)

1. Clone and install everything

git clone https://github.com/birenderpal/mcp-authentication-demo.git
cd mcp-authentication-demo
npm run install:all

2. Deploy the Amplify backend

cd client

# Deploy your backend

npx amplify deploy   # For deploying to your AWS account

# OR

npx ampx sandbox  # For local testing with a sandbox environment

This sets up:

• Cognito User Pool
• Identity Pool
• OAuth App Clients

3. Update the server config

Use the values from client/amplify_outputs.json and set them in .env or config file:

PORT=3001
AWS_REGION=us-west-2
COGNITO_USER_POOL_ID=us-west-2_XXXXX
COGNITO_IDENTITY_POOL_ID=us-west-2:xxxx-xxxx-xxxx
AVP_POLICY_STORE_ID=ps-xxxxxxxx

🧪 Running the demo

To run both frontend and server:

npm run dev

Or separately:

npm run client:dev
npm run server:dev

🔐 AVP Setup (Authorization Policies)

You’ll need to create a policy store and load a schema/policy manually.

1. Create the policy store

aws verifiedpermissions create-policy-store   --validation-settings mode=ON   --region us-west-2

2. Upload your schema

Save this as schema.json:

{
  "MCP": {
    "entityTypes": {
      "Server": {
        "shape": {
          "type": "Record",
          "attributes": {
            "entityId": {
              "type": "String",
              "required": true
            }
          }
        }
      },
      "Tool": {
        "shape": {
          "type": "Record",
          "attributes": {
            "entityId": {
              "type": "String",
              "required": true
            }
          }
        }
      },
      "Client": {
        "shape": {
          "type": "Record",
          "attributes": {
            "entityId": {
              "type": "String"
            },
            "scope": {
              "type": "Set",
              "element": {
                "type": "String"
              }
            }
          }
        }
      }
    },
    "actions": {
      "connect": {
        "appliesTo": {
          "context": {
            "type": "Context"
          },
          "principalTypes": [
            "Client"
          ],
          "resourceTypes": [
            "Server"
          ]
        }
      },
      "call": {
        "appliesTo": {
          "context": {
            "type": "Context"
          },
          "principalTypes": [
            "Client"
          ],
          "resourceTypes": [
            "Tool"
          ]
        }
      }
    },
    "commonTypes": {
      "Context": {
        "type": "Record",
        "attributes": {
          "token": {
            "type": "Record",
            "attributes": {
              "scope": {
                "type": "Set",
                "element": {
                  "type": "String"
                }
              },
              "client_id": {
                "type": "String"
              }
            }
          }
        }
      }
    }
  }
}

Then apply it:

aws verifiedpermissions put-schema   --policy-store-id <your-policy-store-id>   --definition file://schema.json   --region us-west-2

3. Link your Cognito user pool

aws verifiedpermissions create-identity-source   --policy-store-id <your-policy-store-id>   --principal-entity-type "MCP::Client"   --configuration cognitoUserPoolConfiguration="{userPoolArn='arn:aws:cognito-idp:us-west-2:<account-id>:userpool/us-west-2_xxxx'}"   --region us-west-2

4. Add a Cedar policy

Save this as policy.cedar:

permit (principal, action, resource)
when {
  context has token &&
  context.token has scope &&
  context.token.scope.contains(resource.entityId)
};

Create it:

aws verifiedpermissions create-policy   --policy-store-id <your-policy-store-id>   --definition file://policy.cedar   --region us-west-2

🔧 Identity Pool Role Mapping

After deploying Amplify:

1. Go to Cognito Identity Pools in AWS Console
2. Edit the pool created by Amplify
3. Assign an IAM role to authenticated users
4. Save changes

This is required so users can get temporary AWS credentials when they log in.

📄 License

MIT