Skip to content

Refactor MCP Permissions documentation to Agent Security terminology #610

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
danyi1212 wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Refactor MCP Permissions documentation to Agent Security terminology #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
211 changes: 106 additions & 105 deletions docs/ai-security/mcp-permissions/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,48 @@
---
title: MCP Permissions Architecture
title: Agent Security Architecture
sidebar_label: Architecture
description: A comprehensive guide to MCPermit's architecture, explaining how it delivers permissions-as-a-service for Model Context Protocol servers.
description: A comprehensive guide to Agent Security's architecture, explaining how it delivers permissions-as-a-service for Model Context Protocol servers.
sidebar_position: 2
---

# MCP Permissions Architecture
# Agent Security Architecture

:::info
This pages describes an upcoming product; details are subject to change.
To get early access to MCPermit, contact us via [email](mailto:support@permit.io) or via [Slack](https://io.permit.io/slack).
:::
## What is Agent Security?

## What is MCPermit?

MCPermit delivers **permissions-as-a-service** for any Model Context Protocol (MCP) server-hosted or self-managed. It acts as a proxy/gateway between AI agents and the resources they invoke, providing:
Agent Security delivers **permissions-as-a-service** for any Model Context Protocol (MCP) server. It acts as a proxy/gateway between AI agents and the resources they invoke, providing:

* **Fine-grained ReBAC** (relationship-based access control) powered by Permit.io, OPA, and OPAL
* **Five-stage authentication & authorization** that binds user, agent, MCP server, and downstream service identities
* **Comprehensive auditing and anomaly detection** covering every call, scope, and actor
* **Authentication & authorization** that binds user, agent, MCP server, and downstream service identities
* **Comprehensive auditing** covering every call, scope, and actor
* **Flexible delivery models** that share identical policy semantics

A single URL switch yields consistent enforcement, instant visibility, and human-in-the-loop (HITL) approvals-**no code changes** to agents or servers.
A single URL switch yields consistent enforcement, instant visibility, and human-in-the-loop (HITL) approvals — **no code changes** to agents or servers.

## Core Components

```mermaid
graph LR
subgraph Client Side
UA[Originator<br/>User]
AGT[n8n-email-workflow-agent<br/>MCP Client]
AGT[MCP Client<br/>Cursor / Claude / VS Code]
end

subgraph MCPermit Gateway / Middleware
GW[MCPermit<br/>Gateway]
subgraph Agent Security Gateway
GW[Gateway]
PDP[Permit.io PDP<br/>OPA + OPAL]
LOGS[Audit Store]
HIL[HITL Approvals]
HIL[HITL Approvals<br/>coming soon]
end

subgraph Resource Side
MCP1[Google-Gsuite-MCP]
MCP2[Calendly-MCP-sorter]
MCP2[Calendly-MCP]
SVC1[Google APIs]
SVC2[Calendly API]
end

UA -->|OAuth / SSO| GW
AGT -->|identify_self| GW
UA -->|OAuth| GW
AGT -->|MCP Streamable HTTP| GW
GW --> PDP
GW --> LOGS
GW --> HIL
Expand All @@ -58,137 +53,144 @@ graph LR
```

Key components:
- **Gateway**: Can be SaaS, self-hosted proxy, or in-process middleware
- **Permit.io PDP**: Runs embedded (WASM) for µ-latency or remotely via OPAL
- **Audit Store**: Feeds live anomaly detection
- **HITL service**: Issues approval links and manages step-up auth
- **Gateway**: Managed proxy at `*.agent.security`
- **Permit.io PDP**: Policy decision point for real-time authorization
- **Audit Store**: Records every authorization decision
- **HITL service** *(coming soon)*: Issues approval links and manages step-up auth

## Integration Patterns

MCPermit offers three deployment patterns:
Agent Security currently offers a hosted gateway deployment. Additional patterns are planned:

| Pattern | When to Use | How It Works |
| ------------------------- | -------------------------------- | ----------------------------------------------------------------- |
| **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<org>.mcpermit.io` |
| **Side-car / Middleware** | Low-latency, on-prem AI | Drop a lightweight proxy library in front of the MCP server |
| **Hosting Platform** | Building a multi-tenant MCP SaaS | MCPermit baked into ingress; tenants consume via hosted endpoints |
| Pattern | When to Use | How It Works | Status |
| ------------------------- | -------------------------------- | ----------------------------------------------------------------- | ------ |
| **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security` | Available |
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The hosted gateway URL shown here omits the /mcp path, but elsewhere (e.g., the Getting Started guide) the MCP endpoint is https://<host>.agent.security/mcp. This mismatch is likely to cause misconfiguration; update the URL in this table (or clarify base vs MCP endpoint) to be consistent.

Suggested change
| **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security` | Available |
| **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security/mcp` | Available |

Copilot uses AI. Check for mistakes.
| **Side-car / Middleware** | Low-latency, on-prem AI | Drop a lightweight proxy library in front of the MCP server | *Coming soon* |
| **Hosting Platform** | Building a multi-tenant MCP SaaS | Agent Security baked into ingress; tenants consume via hosted endpoints | *Coming soon* |

All patterns share one control plane, policy model, and log format.
All patterns will share one control plane, policy model, and log format.

## Policy Model

### Five-Stages of Access Control
### Trust-Level Access Control

Agent Security provides trust-level-based policy control where each tool is classified by risk:

1. **Low trust** — read-only operations (`get_*`, `list_*`, `read_*`)
2. **Medium trust** — write operations (`create_*`, `update_*`, `send_*`)
3. **High trust** — destructive operations (`delete_*`, `remove_*`, `destroy_*`)

MCPermit provides five levels of policy control:
Trust levels are hierarchical: higher levels inherit all permissions from lower levels.

1. **Organization Policy** – controls *agent-type ↔ server-type* pairings
2. **User Policy** – user delegates a concrete agent
3. **Agent Permission** – coarse scopes (`read_emails`, `create_event`)
4. **Operation Approval** – per-call HITL step-up
5. **Org-Wide Constraints** – DLP masks, region pinning, rate limits
### Planned Policy Enhancements *(coming soon)*

- **Organization Policy** — control agent-type ↔ server-type pairings
- **Operation Approval** — per-call HITL step-up
- **Org-Wide Constraints** — DLP masks, region pinning, rate limits

### Policy Architecture

MCPermit automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on:
Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on:
Copy link

Copilot AI Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hyphenate the compound modifier: change 'Relationship based' to 'Relationship-based' for correct grammar.

Suggested change
Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on:
Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship-based Access Control) policies based on:

Copilot uses AI. Check for mistakes.
- Defined roles for users and agents
- MCP Server types (e.g. Personal, Corporate, sensitive, pro-active)
- Role derivation from user profiles to agents
- MCP server resource instances
- Role derivation from user consent to agent permissions

```mermaid
graph TD
A[Agent] --Role--> O[Originator User Profile -RI-]
O --Relation--> M[MCP Server -RI-]
O --Relation--> M1[MCP Server -RI-]
O --Relation--> M2[MCP Server -RI-]
M --Relation--> F[MCP Function -RI-]
M1 --Relation--> F1[MCP Function -RI-]
M2 --Relation--> F2[MCP Function -RI-]
A[Agent] --Trust Level Role--> M[MCP Server Instance]
M --Has Actions--> F1[Tool: get_issues]
M --Has Actions--> F2[Tool: create_issue]
M --Has Actions--> F3[Tool: delete_repo]
```

## Authentication & Authorization

### Token Taxonomy
### How it Works

When a user connects an MCP client through the gateway for the first time:

| Stage | Actor | Carrier | Purpose |
| ----: | ------------------------ | -------------------------------- | ----------------------- |
| **1** | User (Originator) | OIDC JWT (`sub`) | Enterprise identity |
| **2** | Agent | Client creds / mTLS (`agent_id`) | Agent identity |
| **3** | Agent → Gateway | MCPOAuth (`azp`, `scp`) | Requested scopes |
| **4** | Gateway → MCP | **On-demand** service token | Least-privilege |
| **5** | Agent OBO User → Service | [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693) token exchange | User context downstream |
1. The MCP client discovers the gateway's OAuth endpoints
2. The user authenticates and completes the consent flow
3. The user selects a trust level for the MCP server
4. The gateway issues a JWT access token to the MCP client

### Sequence Flows
On subsequent tool calls:

#### First-Run Delegation
1. The gateway verifies the JWT and identifies the agent
2. The gateway checks Permit: *"Can this agent call this tool on this MCP server?"*
3. Allowed calls are proxied; denied calls return an error

### Sequence: First-Time Connection

```mermaid
sequenceDiagram
participant U as Originator
participant A as Agent
participant G as MCPermit Gateway
participant H as HITL Approval
participant P as PDP

U->>A: Configure agent URL Gateway
A->>G: identify_self
G-->>A: 302 approval_link
A->>U: Show consent UI
U->>H: Login + approve
H--)G: grant_delegation
G->>P: upsert user agent
G-->>A: 200 agent_token
participant U as User
participant C as MCP Client
participant G as Agent Security Gateway
participant CS as Consent Service

C->>G: POST /mcp (no token)
G-->>C: 401 + OAuth discovery
C->>CS: Authorization request
CS-->>C: Redirect to login
U->>CS: Login + consent + trust level
CS-->>C: Authorization code
C->>CS: Exchange for token
CS-->>C: JWT access token
C->>G: POST /mcp (Bearer token)
G-->>C: MCP response
```

#### Authorized Call
### Sequence: Authorized Tool Call

```mermaid
sequenceDiagram
participant A as Agent
participant C as MCP Client
participant G as Gateway
participant P as PDP
participant M as MCP Server
participant S as Downstream Service

A->>G: invoke read_emails
G->>P: is_allowed?
P-->>G: PERMIT
G->>M: read_emails with JWT user+agent
M->>S: Gmail API with OBO token
S-->>M: data
M-->>G: data
G-->>A: data
G->>Audit: log event
participant P as Permit PDP
participant M as Upstream MCP Server

C->>G: call_tool(name=create_issue)
G->>P: permit.check(agent, create_issue, mcp_server)
alt allowed
P-->>G: PERMIT
G->>M: call_tool (proxied)
M-->>G: tool result
G-->>C: tool result
else denied
P-->>G: DENY
G-->>C: Permission denied
end
G->>G: Log to audit
```

## Deployment Options
## Deployment

Agent Security is currently available as a **hosted gateway** at `*.agent.security`. Each host (tenant) gets a unique subdomain with isolated policies, users, and sessions.

### Gateway PDP Options
### Planned Deployment Options *(coming soon)*

| Deployment | Latency (P95) | Isolation | Updates |
| ----------------- | ------------- | ----------- | --------------------- |
| **Embedded WASM** | < 10 ms | Per-gateway | Rego/Data via OPAL |
| **Remote PDP** | 10-30 ms RTT | Centralized | Horizontal scale |

Choose *Embedded* for air-gapped or ultra-low-latency; *Remote* for central governance.

:::info
With MCPermit hybrid mode, you can start with embedded PDP for low-latency enforcement and then connect it to remote control plane for centralized policy management.
:::

## Key Advantages

* **Single control point** for authZ, audit, anomaly detection
* **Drop-in**-no code changes, SDK optional
* **Fine-grained ReBAC**-captures true user-agent-resource relationships
* **Policy-as-code**-Rego, GitOps, unit tests
* **Short-lived creds**-minimize blast radius
* **HITL safety net**-step-up approvals for risky ops
* **DLP hooks**-mask/redact before LLM exposure
* **Single control point** for authZ, audit, and anomaly detection
* **Drop-in** — no code changes, SDK optional
* **Fine-grained ReBAC** — captures true user-agent-resource relationships
* **Policy-as-code** — Rego, GitOps, unit tests
* **Short-lived creds** — minimize blast radius
* **HITL safety net** *(coming soon)* — step-up approvals for risky ops
* **DLP hooks** *(coming soon)* — mask/redact before LLM exposure

## Future Roadmap
## Roadmap

| Area | Next Step |
| ---------------------- | -------------------------------------------------- |
| **HITL Approvals** | Configurable step-up approvals for sensitive operations |
| **Enterprise SSO** | OIDC, SAML, LDAP integration |
| **DLP** | Client-side classifiers, inline redaction |
| **Secrets-on-Demand** | Vault-backed token minting |
| **Policy Analytics** | Graph-diff to flag over-permissioned agents |
Expand All @@ -205,15 +207,14 @@ Below is an example of how different agents can be configured with various roles
| Security Monitor | security_analyst, alert_manager | security_team_789 | ambient | security_mcp_1, security_mcp_2 |
| Code Review Bot | code_reviewer, pr_assistant | dev_team_101 | proactive | dev_mcp_1 |
| Data Analyst | data_processor, report_generator | analytics_team_202 | chat | analytics_mcp_1, analytics_mcp_2 |
| System Monitor | system_admin, health_checker | ops_team_303 | ambient | ops_mcp_1, ops_mcp_2, ops_mcp_3 |

## Glossary

| Term | Meaning |
| -------------- | ---------------------------------------------------- |
| **MCP** | Model Context Protocol (tool/agent interoperability) |
| **Originator** | Human delegating authority |
| **Agent** | Autonomous MCP client acting OBO the user |
| **Agent** | Autonomous MCP client acting on behalf of the user |
| **HITL** | Human-in-the-loop |
| **ReBAC** | Relationship-based access control |
| **OPAL** | Open Policy Administration Layer |
Expand Down
Loading