diff --git a/docs/permit-mcp-gateway/advanced-features.mdx b/docs/permit-mcp-gateway/advanced-features.mdx index d2143887..2e758612 100644 --- a/docs/permit-mcp-gateway/advanced-features.mdx +++ b/docs/permit-mcp-gateway/advanced-features.mdx @@ -1,50 +1,140 @@ --- title: Advanced Features sidebar_label: Advanced Features -description: Explore Agent Security's Enterprise capabilities — agent fingerprinting, in-session monitoring, shadow agent detection, HITL approvals, intent-based access control, permission receipts, and time-limited consent. +description: Explore Permit MCP Gateway's enterprise capabilities — human-in-the-loop approvals, time-limited consent, agent verification, and additional security controls. sidebar_position: 9 --- # Advanced Features -Agent Security's Enterprise plan unlocks deeper security controls for organizations that need to go beyond authentication and trust levels — with behavioral verification, real-time monitoring, human approval workflows, and compliance-grade audit trails. +Permit MCP Gateway's Enterprise plan includes additional security controls for organizations that need to go beyond standard authentication and trust levels. :::note Enterprise Plan -The features on this page are available on **Enterprise** plans. [Schedule a demo](https://calendly.com/permit-io/demo) to see them in action. +The features on this page are available on **Enterprise** plans. Some features described below may be in early access or under active development. [Schedule a demo](https://calendly.com/permit-io/demo) to discuss availability, maturity, and fit for your use case. ::: -## Agent Fingerprinting +## Agent Interrogation -Confirm that each connecting agent is what it claims to be. Agent Fingerprinting builds a behavioral profile when an agent connects, detecting impersonation, credential sharing, and unexpected changes — before any tool call is authorized. +Traditional identity systems were built for humans and static services. Agents are different — they are non-deterministic, their prompts and toolchains can change between sessions, and a single MCP client connection may multiplex multiple contexts. Standard OAuth client IDs identify *the tool*, not *the agent's actual identity and intent*. -## In-Session Monitoring +Agent Interrogation is an agentic-native identity mechanism built into the gateway. Before any tools are unlocked, the gateway directly engages the connecting agent through the MCP protocol itself — requiring it to identify itself and its purpose. This produces a **persistent, composite agent identity** that goes beyond client credentials to capture *who the agent is, who it acts for, and what it intends to do*. -Gain visibility into what agents do _during_ a session, not just at the gateway boundary. In-session monitoring tracks how an agent chains tool calls, what data it accumulates, and whether its behavior matches its declared purpose — enabling real-time anomaly detection and policy enforcement from within the session. +### How It Works -## Shadow Agent Detection +When an agent connects to the gateway, it initially sees only a single tool: `identify_self`. All other tools are gated behind this step. The agent must complete an interrogation exchange before the full tool catalog is unlocked. This approach is agentic-native — it uses the same MCP protocol the agent already speaks, requiring no additional SDKs, side channels, or client modifications. -Discover unauthorized AI agents connecting to your MCP servers outside of approved channels. Shadow Agent Detection identifies rogue connections through behavioral analysis and traffic pattern recognition — even when they bypass the gateway entirely — and alerts your security team. +The interrogation produces a **composite agent identity** that binds three dimensions: -## Human in the Loop (HITL) +- **The delegating human** — the authenticated user accountable for the agent's actions +- **The workflow context** — the operational frame in which the agent acts (e.g., "code review assistant for the platform team" vs. "personal research assistant") +- **The agent fingerprint** — a stable, probabilistic identity signature derived from the agent's own responses, representing its behavioral characteristics and intent -Require human approval for high-risk agent actions. When an agent requests a sensitive operation — such as deleting records, transferring funds, or accessing personal data — the gateway pauses execution and routes an approval request to a designated reviewer. Routine operations continue uninterrupted. +This composite identity becomes the subject used for all subsequent policy evaluation, audit logging, and drift detection. -## Intent-Based Access Control +### Value for Policy Enforcement -Define what each agent is allowed to do by declaring its intended purpose up front. The gateway evaluates the agent's declared intent against policy before execution begins — enabling holistic access checks, conflict detection, and risk assessment across multi-step workflows. +Agent Interrogation gives the policy engine a richer identity to reason about than a bare client ID: -## Permission Receipts +- **Hard-gate tool access** — no tools are accessible until the agent has identified itself. This ensures that every tool call in the system is tied to a verified agent identity. +- **Per-workflow policy** — because the interrogation captures the agent's operational context, admins can define different trust levels and tool access for the same MCP client operating in different workflows. +- **Drift-triggered policy reactions** — if an agent's fingerprint deviates meaningfully from its established baseline (indicating a changed system prompt, model swap, or prompt injection), the gateway can automatically respond: downgrade trust, require re-consent, block execution, or route to human approval. These reactions are policy-driven and configurable per workflow. +- **Step-up consent on intent mismatch** — when an agent declares destructive or sensitive capabilities during interrogation, policy can require additional human approval before granting access. + +### Value for Auditing and Governance + +Every agent session begins with a declarative record of who the agent is and what it intends to do: + +- **Persistent identity across sessions** — the fingerprint provides continuity. Security teams can track a specific agent's behavior over time, even across client restarts and re-connections. +- **Declared intent vs. observed behavior** — during interrogation, the agent declares what tools it expects to call and what data it expects to access. This declared intent is logged and can be compared against actual tool call patterns during the session, surfacing unexpected deviations for review. +- **Full identity chain in audit logs** — every tool call is attributed to the composite identity: the human who delegated, the workflow context, the verified agent fingerprint, and the session. This gives compliance and security teams the full chain of accountability. +- **Drift history** — fingerprint changes over time are tracked, giving admins visibility into when and how agent behavior shifts. + +### Value for Prompt Injection Protection -Get auditable, signed records of every permission grant — who approved it, which agent, which MCP server, which tools, the trust level, and when it expires. Receipts provide a tamper-evident audit trail for compliance and governance, and can be downloaded individually or exported in bulk. +Agent Interrogation provides a detection layer against prompt injection and agent manipulation: + +- **Baseline fingerprinting** — a legitimate agent produces a consistent identity signature across sessions. If a prompt injection alters the agent's system prompt or behavioral context, the resulting fingerprint will diverge from the established baseline, triggering a drift alert. +- **Multi-dimensional drift detection** — the fingerprint captures multiple independent dimensions (agent intent, delegator context, operational environment). An attack that manipulates one dimension — for example, injecting instructions to impersonate a different workflow — is likely to cause measurable drift even if other dimensions remain stable. +- **Session isolation** — by binding identity to the specific agent context rather than just the client connection, interrogation reduces the risk of session confusion in multiplexed MCP client connections, where a compromised context could otherwise access permissions granted to a different context on the same connection. + +Agent Interrogation does not fully prevent prompt injection — that remains a defense-in-depth challenge across the agent stack. It provides an additional detection and enforcement layer at the gateway boundary that is particularly valuable because it operates on the agent's own self-reported identity, making it sensitive to the kinds of behavioral shifts that prompt injections cause. + +:::note Maturity +Agent Interrogation is under active development as an Enterprise capability. The interrogation protocol, fingerprinting methodology, and drift detection thresholds are being refined. [Contact us](mailto:support@permit.io) for current status, early access, and roadmap details. +::: + +--- + +## Human-in-the-Loop Approvals (HITL) + +Require human approval for high-risk agent actions. When an agent requests a sensitive operation — such as deleting records, modifying production data, or accessing restricted resources — the gateway pauses execution and routes an approval request to a designated reviewer. Routine operations continue without interruption. + +This is useful for organizations that want to allow agents to attempt sensitive actions but require a human to confirm before execution proceeds. ## Time-Limited Consent -Set custom consent windows that automatically expire. For example, grant a contractor's agent two-week access — when the window closes, access is revoked automatically. If the engagement extends, the user simply re-consents through the standard flow. +Set custom consent windows that automatically expire. For example, grant a contractor's agent two-week access — when the window closes, access is revoked automatically. If the engagement extends, the user re-consents through the standard flow. :::info -All plans include built-in session expiry (90-day hard / 30-day inactivity). Enterprise adds fully configurable consent windows for fine-grained control. +All plans include built-in session expiry (90-day hard / 30-day inactivity). Enterprise adds fully configurable consent windows for fine-grained control over access duration. +::: + +## Agent Verification + +Verify that connecting agents match expected behavioral and identity characteristics. Agent verification builds a profile when an agent connects, which can be used to detect unexpected changes in agent identity or behavior over time. + +[Agent Interrogation](#agent-interrogation) provides the underlying mechanism for agent verification — the fingerprint generated during interrogation serves as the persistent identity baseline against which subsequent connections are compared. + +:::note Maturity +Agent verification capabilities (including behavioral profiling and drift detection) are under active development. Specific detection capabilities and accuracy characteristics may vary. [Contact us](mailto:support@permit.io) for current status and roadmap details. +::: + +## Session Monitoring + +Gain visibility into what agents do during a session, not just at the gateway boundary. Session monitoring tracks tool call patterns within a session, providing additional context for security review and incident investigation. + +When combined with [Agent Interrogation](#agent-interrogation), session monitoring can compare an agent's declared intent (captured during interrogation) against its actual tool call behavior, surfacing deviations for review. + +:::note Maturity +Session monitoring capabilities (including anomaly detection and behavioral analysis) are under active development. [Contact us](mailto:support@permit.io) for current status and availability. +::: + +## Permission Receipts + +Get auditable records of every permission grant — who approved it, which agent, which MCP server, which tools, the trust level, and when it expires. Receipts provide an audit trail for compliance and governance, and can be exported for external review. + +## Intent-Based Access Control + +Define what each agent is allowed to do by declaring its intended purpose up front. The gateway can evaluate the agent's declared intent against policy before execution begins — enabling access checks that consider the overall workflow, not just individual tool calls. + +[Agent Interrogation](#agent-interrogation) is the mechanism through which intent is captured — during the interrogation exchange, the agent declares its purpose and expected tool usage, which policy can then use for access decisions. + +:::note Maturity +Intent-based access control is an emerging capability. [Contact us](mailto:support@permit.io) for current status and roadmap. +::: + +--- + +## Feature Maturity Summary + +| Feature | Status | Notes | +| --- | --- | --- | +| **Agent Interrogation** | Enterprise, active development | Agentic-native identity, fingerprinting, drift detection, and prompt injection defense | +| **Human-in-the-Loop Approvals** | Enterprise | Available for enterprise plans | +| **Time-Limited Consent** | Enterprise | Available for enterprise plans | +| **Agent Verification** | Enterprise, early access | Behavioral profiling and drift detection, powered by Agent Interrogation | +| **Session Monitoring** | Enterprise, early access | Anomaly detection capabilities under active development | +| **Permission Receipts** | Enterprise | Available for enterprise plans | +| **Intent-Based Access Control** | Enterprise, roadmap | Declared intent captured via Agent Interrogation, policy evaluation emerging | + +:::info Items flagged on the marketing site but not yet detailed in documentation +The following capabilities have been referenced in marketing materials but are not yet fully documented. Contact us for current status: + +- **Sub-millisecond authorization decisions** — performance characteristics depend on deployment model and policy complexity. Contact us for benchmark details. +- **Anomaly detection** — behavioral anomaly detection for agent sessions is under development as part of session monitoring. +- **Shadow agent detection** — detection of unauthorized agents connecting outside the gateway is an area of active research. Availability and detection methodology details are available on request. ::: --- -**Ready to upgrade?** [Schedule a demo](https://calendly.com/permit-io/demo) or reach out at [support@permit.io](mailto:support@permit.io). You can also find us on [Slack](https://io.permit.io/slack). +**Interested in Enterprise features?** [Schedule a demo](https://calendly.com/permit-io/demo) or reach out at [support@permit.io](mailto:support@permit.io). You can also find us on [Slack](https://io.permit.io/slack). diff --git a/docs/permit-mcp-gateway/architecture.mdx b/docs/permit-mcp-gateway/architecture.mdx index aa336189..66afd207 100644 --- a/docs/permit-mcp-gateway/architecture.mdx +++ b/docs/permit-mcp-gateway/architecture.mdx @@ -1,24 +1,73 @@ --- -title: Agent Security Architecture -sidebar_label: Architecture Deep Dive -description: A comprehensive guide to Agent Security's architecture, explaining how it delivers permissions-as-a-service for Model Context Protocol servers. +title: Architecture +sidebar_label: Architecture +description: Technical architecture of Permit MCP Gateway — components, data flows, authorization model, and deployment patterns. sidebar_position: 7 --- import ZoomableDiagram from '@site/src/components/ZoomableDiagram'; -# Agent Security Architecture +# Permit MCP Gateway Architecture -## What is Agent Security? +## Executive Summary -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 MCP server resources they interact with, providing: +Permit MCP Gateway is a proxy that sits between MCP clients and upstream MCP servers. When an MCP client connects, the gateway handles authentication (via a consent service), checks every tool call against fine-grained policy (via Permit.io), and logs every decision for audit. + +**The key architectural properties are:** + +- **Transparent proxy** — MCP clients connect to the gateway URL instead of the upstream server URL. The upstream MCP server receives proxied requests and does not need to be modified. +- **Identity binding** — every tool call is tied to a specific human (who authenticated) and agent (the MCP client acting on their behalf), using a relationship-based access control model. +- **Real-time policy enforcement** — the gateway calls `permit.check()` on every `call_tool` request. Decisions are based on the agent's trust level, the human's trust ceiling, and the tool's risk classification. +- **Stateful sessions** — upstream OAuth tokens and consent state are stored server-side (in Redis), so users do not re-authenticate on every connection. +- **Multi-tenant isolation** — each host (gateway instance) has its own subdomain, policies, users, and sessions. + +The rest of this page covers the detailed component architecture, data flows, and authorization model. + +--- + +## Permit.io as Control Plane and Data Plane + +Permit.io serves as both the **control plane** and the **default data plane** for Permit MCP Gateway. + +- **Control plane**: Permit.io is where the authorization model is defined — resource types, actions, roles, relations, derived roles, and role assignments. The gateway dashboard ([app.agent.security](https://app.agent.security)) and the Consent Service write policy changes to Permit via its Platform API. Admins can also inspect and manage policies directly in the Permit dashboard ([app.permit.io](https://app.permit.io)). +- **Data plane**: The Permit PDP (Policy Decision Point) evaluates every `permit.check()` call from the gateway at runtime. In the hosted deployment, the cloud PDP handles these evaluations. In customer-controlled deployments, a local PDP can be used so that authorization decisions stay within your network. + +Every gateway **host** maps 1:1 to a **Permit environment**. This binding is established when the admin creates a host and selects a Permit project and environment. All resources, users, roles, and audit logs for that host live in the linked environment. + +```mermaid +flowchart LR + subgraph "Gateway (*.agent.security)" + Host["Host
acme-brave-coral-37"] + GW["Gateway"] + CS["Consent Service"] + end + + subgraph "Permit.io (Control Plane + Data Plane)" + Env["Permit Environment
(linked to host)"] + PDP["Permit PDP"] + Audit["Audit Logs"] + end + + Host --- Env + CS -->|"Write policy
(roles, relations)"| Env + GW -->|"permit.check()
(every tool call)"| PDP + PDP -->|"Log decision"| Audit +``` + +This means the full power of Permit's policy engine is available to the gateway — including RBAC, ABAC, and ReBAC models, real-time policy updates via OPAL, and the complete audit log API. + +--- + +## Technical Architecture + +Permit MCP Gateway delivers **permissions-as-a-service** for any MCP server. It provides: * **Fine-grained ReBAC** (relationship-based access control) powered by Permit.io (which uses OPA and OPAL under the hood) -* **Authentication & authorization** that binds user, agent, MCP server, and downstream service identities +* **Authentication and authorization** that binds user, agent, MCP server, and downstream service identities * **Comprehensive auditing** covering every tool call, user, and agent -* **Flexible deployment options** (hosted gateway available), all using the same policy rules +* **Hosted gateway deployment**, with all components using the same policy rules -A single URL switch yields consistent enforcement, instant visibility, and human-in-the-loop (HITL) approvals — **no code changes** to agents or servers. +Adopting the gateway requires a single configuration change — pointing your MCP client at the gateway URL instead of directly at the upstream server. ## System Architecture Overview @@ -74,11 +123,11 @@ flowchart LR **Key components:** - **Platform** (`app.agent.security`): Admin interface for managing hosts, MCP servers, and user access -- **Edge Router** (NGINX): Routes requests by path to Gateway or Consent Service +- **Edge Router** (NGINX): Routes requests by path to the Gateway or Consent Service - **Gateway** (`*.agent.security/mcp`): MCP proxy that enforces authorization on every tool call - **Consent Service** (`*.agent.security`): Handles OAuth login, user consent, and upstream MCP OAuth - **Permit.io PDP**: Policy decision point for real-time authorization checks -- **Redis**: Session and host configuration store (accessed only by Gateway) +- **Redis**: Session and host configuration store (accessed only by the Gateway) - **PostgreSQL**: User accounts, OAuth clients, and auth sessions :::info Architecture constraint @@ -140,7 +189,7 @@ flowchart TD ## Integration Patterns -Agent Security is available as a hosted gateway deployment: +Permit MCP Gateway is available as a hosted gateway deployment: | Pattern | When to Use | How It Works | | ------------------------- | -------------------------------- | ----------------------------------------------------------------- | @@ -150,7 +199,7 @@ Agent Security is available as a hosted gateway deployment: ### Trust-Level Access Control -Agent Security classifies each tool into a trust level based on its risk: +Permit MCP Gateway classifies each tool into a trust level based on its risk: 1. **Low trust** — everything else (read-only by convention); this is the default for tools not matching medium or high patterns 2. **Medium trust** — write operations (tools containing: `create`, `write`, `update`, `set`, `modify`, `edit`, `put`, `post`, `insert`, `add`, `send`, `execute`, `run`, `invoke`, `submit`, `push`, `publish`, `deploy`, `apply`, `patch`) @@ -160,7 +209,7 @@ Trust levels are hierarchical: higher levels inherit all permissions from lower ### Policy Architecture -Agent Security automatically generates [Google-Zanzibar](/modeling/google-drive)-inspired ReBAC (Relationship-based Access Control) policies based on: +Permit MCP Gateway automatically generates [Google-Zanzibar](/modeling/google-drive)-inspired ReBAC (Relationship-based Access Control) policies based on: - Defined roles for users and agents - MCP server resource instances - Agent roles derived from the user's consent choices @@ -296,7 +345,7 @@ sequenceDiagram ``` :::info Server allow-list -By default, users can only connect to MCP servers that the admin has pre-configured and granted them access to — the consent service validates that every upstream URL matches a server the user is authorized to use. However, if the admin enables **Dynamic MCPs** on the host, users can also enter arbitrary upstream MCP server URLs during the consent flow. See [Dynamic MCPs](#dynamic-mcps) below. +By default, users can only connect to MCP servers that the admin has pre-configured and granted them access to — the Consent Service validates that every upstream URL matches a server the user is authorized to use. However, if the admin enables **Dynamic MCPs** on the host, users can also enter arbitrary upstream MCP server URLs during the consent flow. See [Dynamic MCPs](#dynamic-mcps) below. ::: ### Sequence: Authorization Decision Flow @@ -314,9 +363,9 @@ sequenceDiagram C->>GW: call_tool(name=create_issue, Bearer token) Note over GW: 1. Extract tenant from Host header - Note over GW: Host: acme-pink-panda-6942.agent.security + Note over GW: Host: acme-brave-coral-37.agent.security - GW->>R: GET host_lookup:acme-pink-panda-6942 + GW->>R: GET host_lookup:acme-brave-coral-37 Note over GW,R: 2. Load tenant config (permit_api_key, oauth config) Note over GW: 3. JWT Validation @@ -393,17 +442,17 @@ The derived role then determines which tools are allowed: ## Deployment -Agent Security is available as a **hosted gateway** at `*.agent.security`. Each host (tenant) gets a unique subdomain with isolated policies, users, and sessions. +Permit MCP Gateway is available as a **hosted gateway** at `*.agent.security`. Each host (tenant) gets a unique subdomain with isolated policies, users, and sessions. Point your MCP clients to `https://.agent.security/mcp` and the gateway handles the rest — authentication, authorization, and audit logging are all built in. ## Key Advantages -* **Single control point** for authorization and audit -* **Drop-in** — no code changes, SDK optional -* **Fine-grained ReBAC** — captures true user-agent-resource relationships +* **Single enforcement point** for authentication, authorization, consent, and audit +* **Drop-in proxy** — no code changes to MCP clients or servers +* **Fine-grained ReBAC** — models the full user → agent → server → tool relationship chain * **Policy-as-code** — policies managed via UI and API, powered by OPA/Rego under the hood -* **Short-lived creds** — minimize blast radius +* **Credential isolation** — upstream OAuth tokens managed by the gateway, not exposed to MCP clients ## Agent Configuration Examples diff --git a/docs/permit-mcp-gateway/audit-logs.mdx b/docs/permit-mcp-gateway/audit-logs.mdx index 49c92aad..92d63aca 100644 --- a/docs/permit-mcp-gateway/audit-logs.mdx +++ b/docs/permit-mcp-gateway/audit-logs.mdx @@ -1,13 +1,13 @@ --- title: Audit Logs sidebar_label: Audit Logs -description: Understand where audit logs live, what they contain, and how to use them for debugging, compliance, and monitoring in Agent Security. +description: Understand where audit logs live, what they contain, and how to use them for debugging, compliance, and monitoring in Permit MCP Gateway. sidebar_position: 6 --- # Audit Logs -Every authorization decision in Agent Security — every tool call allowed or denied — is logged automatically. This page explains where logs live, what each entry contains, and how to use them. +Every authorization decision in Permit MCP Gateway — every tool call allowed or denied — is logged automatically. This page explains where logs live, what each entry contains, and how to use them for debugging, compliance, and incident investigation. ## Where Audit Logs Live @@ -41,7 +41,7 @@ The Platform surfaces audit logs on three detail pages: For deeper analysis, use the Audit Log in the [Permit.io dashboard](https://app.permit.io): 1. Log in to [app.permit.io](https://app.permit.io) -2. Select the project and environment that matches your Agent Security host +2. Select the project and environment that matches your Permit MCP Gateway host 3. Navigate to the **Audit Log** section The Permit dashboard shows the full policy evaluation chain, including which derived roles were checked and why a decision was made — detail that the Platform UI summarizes. @@ -131,5 +131,61 @@ The Permit Audit Log supports filtering by: 4. For human-centric reports, use the **Human detail page** in the Platform to see all activity under a specific user's authority :::tip Cross-referencing logs -The Permit audit log shows the raw `permit.check()` parameters — user key, action, and resource — making it easy to correlate with the activity views in the [Platform UI](https://app.agent.security). Use the agent's user key (e.g., `agent|cursor_abc123`) to search across both. +The Permit audit log shows the raw `permit.check()` parameters — user key, action, and resource — making it easy to correlate with the activity views in the [Permit MCP Gateway dashboard](https://app.agent.security). Use the agent's user key (e.g., `agent|cursor_abc123`) to search across both. ::: + +## Investigation Examples + +These examples show how to use audit logs to answer common security, debugging, and compliance questions. + +### "Why was this action denied?" + +A developer reports that their agent cannot create issues in Linear despite having access. + +1. Go to the **Agents** page at [app.agent.security](https://app.agent.security) and find the developer's agent (e.g., Cursor) +2. Open the agent's audit log and look for the denied `create_issue` entry +3. Check the **Reason** — if it says "No permission for `create_issue`", the agent's effective trust level is too low. `create_issue` requires **medium** trust. +4. Check the agent's trust level for Linear — if it is **low**, the user needs to re-consent at medium trust +5. Check the human's max trust level on the **Humans** page — if the admin set it to **low**, the admin must raise it before the user can re-consent at medium + +**Resolution:** Either raise the admin's max trust ceiling or have the user re-consent at a higher trust level. + +### "Which human authorized this agent's actions?" + +A security team wants to trace an agent's tool calls back to the authorizing human. + +1. Go to the **Agents** page and find the agent in question +2. The agent detail page shows the **Associated human** — this is the person who completed the consent flow and authorized the agent +3. Open the agent's audit log to see all tool calls with timestamps and decisions +4. Cross-reference with the **Humans** page to see the human's full access grants and all agents acting on their behalf + +**Key insight:** Every agent action in the audit log is traceable to the human who authorized it through the consent flow. The identity chain is: human → consent → agent → tool call. + +### "Which server or tool touched a sensitive system?" + +A compliance team needs to understand all agent interactions with a specific MCP server (e.g., one connected to a production database). + +1. Go to the **MCP Servers** page at [app.agent.security](https://app.agent.security) +2. Select the server in question and open its **Audit Logs** tab +3. Review all tool calls targeting that server — each entry shows which agent called which tool, when, and whether it was allowed or denied +4. Filter by decision to focus on **allowed** calls (to see what actually reached the server) or **denied** calls (to see attempted access that was blocked) +5. For each allowed call, trace back to the authorizing human via the agent's detail page + +**For deeper analysis:** Use the Permit.io dashboard audit log to filter by the server's resource key (e.g., `production-db`) and see the full policy evaluation chain, including which derived roles were checked. + +### "What changed in an agent's access over time?" + +An admin wants to understand the history of an agent's permissions. + +1. Go to the **Agents** page and select the agent +2. Review the audit log timeline — look for patterns like: + - A tool that was previously allowed but is now denied (suggests a trust level change or access revocation) + - A tool that was previously denied but is now allowed (suggests a trust level increase or re-consent) +3. Check the **Humans** page for the authorizing human — the admin's max trust level changes and access revocations are reflected immediately in subsequent tool calls + +### "Generate a compliance report for a specific time period" + +1. In the **Permit.io dashboard** at [app.permit.io](https://app.permit.io), open the Audit Log for the linked environment +2. Set the date range to the reporting period +3. Review or export the entries — each shows: agent identity, human identity (via cross-reference), tool called, MCP server, timestamp, and allow/deny decision +4. For a human-centric view, use the **Humans** page in the Permit MCP Gateway dashboard to see all activity under a specific user's authority across all their agents diff --git a/docs/permit-mcp-gateway/authentication-methods.mdx b/docs/permit-mcp-gateway/authentication-methods.mdx index e8d86481..c9cd82a7 100644 --- a/docs/permit-mcp-gateway/authentication-methods.mdx +++ b/docs/permit-mcp-gateway/authentication-methods.mdx @@ -1,13 +1,13 @@ --- title: Authentication Methods Reference sidebar_label: Authentication Methods -description: Configure how users sign in to Agent Security — email/password, OTP, passkeys, social OAuth, SAML 2.0, and OIDC SSO with IdP-specific setup instructions. +description: Configure how users sign in to Permit MCP Gateway — email/password, OTP, passkeys, social OAuth, SAML 2.0, and OIDC SSO with IdP-specific setup instructions. sidebar_position: 4.5 --- # Authentication Methods Reference -Each Agent Security host has its own authentication configuration, controlling how users sign in during the [consent flow](/permit-mcp-gateway/guide#7-user-consent-flow). Authentication is per-tenant — different hosts can use different methods, credentials, and domain restrictions. +Each Permit MCP Gateway host has its own authentication configuration, controlling how users sign in during the [consent flow](/permit-mcp-gateway/guide#7-user-consent-flow). Authentication is per-tenant — different hosts can use different methods, credentials, and domain restrictions. By default, new hosts have **email/password** enabled and all other methods disabled. @@ -55,9 +55,9 @@ Sign in with Google. ``` https://{subdomain}.agent.security/api/auth/callback/google ``` - Replace `{subdomain}` with your host's full subdomain (e.g., `acme-pink-panda-6942`) + Replace `{subdomain}` with your host's full subdomain (e.g., `acme-brave-coral-37`) 6. Copy the **Client ID** and **Client Secret** -7. In Agent Security, go to your host's **Settings** and enable **Google OAuth** +7. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **Google OAuth** 8. Paste the Client ID and Client Secret :::info Per-host credentials @@ -76,7 +76,7 @@ Sign in with GitHub. 1. Go to [GitHub Developer Settings > OAuth Apps](https://github.com/settings/developers) 2. Click **New OAuth App** 3. Fill in: - - **Application name:** e.g., "Agent Security — acme" + - **Application name:** e.g., "Permit MCP Gateway — acme" - **Homepage URL:** `https://{subdomain}.agent.security` - **Authorization callback URL:** ``` @@ -84,7 +84,7 @@ Sign in with GitHub. ``` 4. Click **Register application** 5. Copy the **Client ID**, then generate and copy a **Client Secret** -6. In Agent Security, go to your host's **Settings** and enable **GitHub OAuth** +6. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **GitHub OAuth** 7. Paste the Client ID and Client Secret ### Microsoft OAuth @@ -99,7 +99,7 @@ Sign in with Microsoft (Azure AD / Entra ID). Supports single-tenant and multi-t 1. Go to the [Azure Portal > App Registrations](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) 2. Click **New registration** 3. Fill in: - - **Name:** e.g., "Agent Security — acme" + - **Name:** e.g., "Permit MCP Gateway — acme" - **Supported account types:** Choose based on your needs: - *Single tenant* — only users in your Azure AD directory - *Multitenant* — users in any Azure AD directory @@ -111,7 +111,7 @@ Sign in with Microsoft (Azure AD / Entra ID). Supports single-tenant and multi-t 4. Click **Register** 5. Copy the **Application (client) ID** 6. Go to **Certificates & secrets > New client secret**, create one, and copy the **Value** -7. In Agent Security, go to your host's **Settings** and enable **Microsoft OAuth** +7. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **Microsoft OAuth** 8. Paste the Client ID and Client Secret 9. *(Optional)* Set the **Tenant ID** to restrict sign-in to a specific Azure AD directory. If omitted, defaults to `common` (multi-tenant — accepts any Azure AD account) @@ -127,7 +127,7 @@ Sign in with Microsoft (Azure AD / Entra ID). Supports single-tenant and multi-t ### SAML 2.0 SSO -Enterprise single sign-on via SAML. Agent Security acts as the **Service Provider (SP)** and your identity provider (Okta, Azure AD/Entra ID, Google Workspace, etc.) acts as the **Identity Provider (IdP)**. +Enterprise single sign-on via SAML. Permit MCP Gateway acts as the **Service Provider (SP)** and your identity provider (Okta, Azure AD/Entra ID, Google Workspace, etc.) acts as the **Identity Provider (IdP)**. - **Configuration required:** IdP entry point URL, IdP entity ID, and X.509 signing certificate (PEM format) @@ -161,7 +161,7 @@ Configure your IdP to send the following SAML attributes: 1. In the Okta Admin Console, go to **Applications > Create App Integration** 2. Select **SAML 2.0** and click **Next** 3. Fill in: - - **App name:** e.g., "Agent Security" + - **App name:** e.g., "Permit MCP Gateway" 4. Configure SAML settings: - **Single sign-on URL (ACS URL):** `https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}` - **Audience URI (SP Entity ID):** `https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata` @@ -175,14 +175,14 @@ Configure your IdP to send the following SAML attributes: - **IdP SSO URL** (entry point) - **IdP Entity ID** (issuer) - **X.509 Certificate** (download and paste as PEM) -8. In Agent Security, go to your host's **Settings** and enable **SAML 2.0 SSO** +8. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **SAML 2.0 SSO** 9. Paste the entry point URL, entity ID, and certificate #### Azure AD (Entra ID) setup 1. In the [Azure Portal](https://portal.azure.com), go to **Enterprise Applications > New Application > Create your own application** 2. Select **Integrate any other application you don't find in the gallery (Non-gallery)** -3. Name it (e.g., "Agent Security") and click **Create** +3. Name it (e.g., "Permit MCP Gateway") and click **Create** 4. Go to **Single sign-on > SAML** 5. In **Basic SAML Configuration**: - **Identifier (Entity ID):** `https://{subdomain}.agent.security/api/auth/sso/saml2/sp/metadata` @@ -191,16 +191,16 @@ Configure your IdP to send the following SAML attributes: - `emailaddress` → `user.mail` - `name` → `user.displayname` 7. In **SAML Certificates**, download **Certificate (Base64)** — this is the PEM-format certificate -8. In **Set up Agent Security**, copy: +8. In **Set up Permit MCP Gateway**, copy: - **Login URL** (entry point) - **Azure AD Identifier** (entity ID) -9. In Agent Security, go to your host's **Settings** and enable **SAML 2.0 SSO** +9. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **SAML 2.0 SSO** 10. Paste the entry point URL, entity ID, and certificate #### Google Workspace setup 1. In the [Google Admin Console](https://admin.google.com), go to **Apps > Web and mobile apps > Add app > Add custom SAML app** -2. Name it (e.g., "Agent Security") and click **Continue** +2. Name it (e.g., "Permit MCP Gateway") and click **Continue** 3. On the **Google Identity Provider details** page, copy: - **SSO URL** (entry point) - **Entity ID** @@ -215,7 +215,7 @@ Configure your IdP to send the following SAML attributes: - `email` → Basic Information > Primary email - `name` → Basic Information > First name + Last name 7. Click **Finish**, then turn the app **ON** for the relevant organizational units -8. In Agent Security, go to your host's **Settings** and enable **SAML 2.0 SSO** +8. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **SAML 2.0 SSO** 9. Paste the entry point URL, entity ID, and certificate ### OIDC SSO @@ -228,13 +228,13 @@ Enterprise single sign-on via OpenID Connect. #### How it works -Agent Security auto-discovers your IdP's endpoints using the standard OpenID Connect Discovery URL: +Permit MCP Gateway auto-discovers your IdP's endpoints using the standard OpenID Connect Discovery URL: ``` {issuerUrl}/.well-known/openid-configuration ``` -You only need to provide the issuer URL — Agent Security handles the rest. +You only need to provide the issuer URL — the gateway handles the rest. #### Setup steps @@ -245,7 +245,7 @@ You only need to provide the issuer URL — Agent Security handles the rest. ``` 3. Note the **Issuer URL** (e.g., `https://accounts.google.com`, `https://login.microsoftonline.com/{tenant}/v2.0`, `https://{domain}.okta.com`) 4. Copy the **Client ID** and **Client Secret** -5. In Agent Security, go to your host's **Settings** and enable **OIDC SSO** +5. In the Permit MCP Gateway dashboard, go to your host's **Settings** and enable **OIDC SSO** 6. Paste the Issuer URL, Client ID, and Client Secret :::note One SSO method per host @@ -360,4 +360,4 @@ When registering OAuth apps or configuring IdPs, use these callback URLs: | **OIDC SSO** | `https://{subdomain}.agent.security/api/auth/callback/sso-{subdomain}` | | **SAML 2.0 ACS** | `https://{subdomain}.agent.security/api/auth/sso/saml2/callback/sso-{subdomain}` | -Replace `{subdomain}` with your host's full subdomain (e.g., `acme-pink-panda-6942`). +Replace `{subdomain}` with your host's full subdomain (e.g., `acme-brave-coral-37`). diff --git a/docs/permit-mcp-gateway/consent-service.mdx b/docs/permit-mcp-gateway/consent-service.mdx index ef7f5b88..65420bab 100644 --- a/docs/permit-mcp-gateway/consent-service.mdx +++ b/docs/permit-mcp-gateway/consent-service.mdx @@ -1,13 +1,13 @@ --- title: Consent Service sidebar_label: Consent Service -description: The Consent Service is the user-facing component where humans authenticate, select MCP servers, set trust levels, and authorize agents — the complete user journey explained. +description: The Consent Service is the user-facing component of Permit MCP Gateway where humans authenticate, select MCP servers, set trust levels, and authorize agents — the complete user journey explained. sidebar_position: 5 --- # Consent Service -The Consent Service is the user-facing component of Agent Security where humans authenticate and grant permissions to their AI agents. It serves as the OAuth 2.1 Authorization Server hosted at each gateway subdomain (e.g., `acme-pink-panda-6942.agent.security`). +The Consent Service is the user-facing component of Permit MCP Gateway where humans authenticate and grant permissions to their AI agents. It serves as the OAuth 2.1 Authorization Server hosted at each gateway subdomain (e.g., `acme-brave-coral-37.agent.security`). When a user connects an MCP client like Cursor or Claude Desktop for the first time, the Consent Service handles the entire authorization flow — from login through trust level selection to issuing the access token that lets the agent make tool calls. @@ -176,7 +176,7 @@ If the upstream MCP server issued OAuth tokens with a refresh token, the Gateway Admins can create URLs that pre-select a specific MCP server in the consent flow by appending the `upstream_mcp` query parameter: ``` -https://acme-pink-panda-6942.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp +https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp ``` When a user connects with this URL: @@ -202,7 +202,7 @@ Admins can set up pre-configured URLs from the [Platform](/permit-mcp-gateway/pl As an alternative to the `upstream_mcp` query parameter, you can use a **path-based URL** that routes directly to a specific static MCP server: ``` -https://acme-pink-panda-6942.agent.security/mcp/linear +https://acme-brave-coral-37.agent.security/mcp/linear ``` Where `linear` is the server key assigned during import. When using this URL, the MCP client connects directly to the specified server — the consent flow still runs (login + trust level selection), but the server selection step is bypassed entirely. diff --git a/docs/permit-mcp-gateway/guide.mdx b/docs/permit-mcp-gateway/guide.mdx index d21598c0..0549aef0 100644 --- a/docs/permit-mcp-gateway/guide.mdx +++ b/docs/permit-mcp-gateway/guide.mdx @@ -1,14 +1,48 @@ --- -title: Getting Started with Agent Security +title: Getting Started with Permit MCP Gateway sidebar_label: Getting Started -description: Set up and manage Agent Security to audit and enforce permissions on MCP server access for your organization. +description: Set up Permit MCP Gateway to authenticate, authorize, and audit MCP server access for your organization — from first host to first authorized tool call. sidebar_position: 2 --- -# Getting Started with Agent Security +# Getting Started with Permit MCP Gateway -The Agent Security Gateway is a managed proxy between MCP clients such as Cursor, Claude Desktop, and VS Code and upstream MCP servers. -It authenticates users, enforces per-tool permissions through trust levels, and logs every tool call for audit. +Permit MCP Gateway is a managed proxy between MCP clients (Cursor, Claude Desktop, VS Code, Claude Code) and upstream MCP servers. It authenticates users, enforces per-tool permissions through trust levels, and logs every tool call for audit. + +## Quick Start: First Value in 5 Minutes + +This fast path gets you from zero to one successful allowed call, one denied call, and one visible audit event. + +:::tip What you will have at the end +- A live gateway URL +- One MCP server imported with auto-classified tools +- One user with granted access +- An MCP client connected through the gateway +- Proof that authorization works: an allowed call and a denied call +- Audit log entries you can inspect +::: + +**Steps:** + +1. **Sign up** at [app.agent.security](https://app.agent.security) and connect your Permit.io organization with an [organization-scoped API key](https://app.permit.io/settings/api-keys) +2. **Create a host** — go to Dashboard → Create Host. Pick a subdomain, project, and environment. Your gateway URL is now live. +3. **Import one MCP server** — go to MCP Servers → Create Server. Enter an upstream URL (e.g., `https://mcp.linear.app/mcp`). Review the auto-classified tools and click Import. +4. **Grant yourself access** — go to Humans, find your user (or add yourself by email), and grant access to the imported server at **medium** trust. +5. **Connect your MCP client** — add the gateway URL to your client config (see [client snippets below](#6-share-with-your-users)). When prompted, sign in and complete the consent flow at **medium** trust. +6. **Test an allowed call** — ask your AI agent to perform a read or write action (e.g., list issues, create an issue). It should succeed. +7. **Test a denied call** — ask your agent to perform a destructive action (e.g., delete something). It should be denied with a permission error. +8. **Check the audit log** — go to the Agents or Humans page in [app.agent.security](https://app.agent.security) and verify that both the allowed and denied calls appear in the activity log. + +If everything worked, your gateway is enforcing policy and logging decisions. Continue below for the detailed setup walkthrough. + +:::note Troubleshooting the quick start +- **No MCP servers in consent screen?** You skipped step 4 — grant yourself access on the Humans page first. +- **Agent bypasses the gateway?** Remove any direct MCP server connection from your client config. Only the gateway URL should remain. +- **OAuth redirect fails?** The upstream MCP server may require manual OAuth credentials. Re-import with Client ID / Secret. +- **Can't find audit logs?** Check both [app.agent.security](https://app.agent.security) (Agent/Human detail pages) and [app.permit.io](https://app.permit.io) (Audit Log in the linked environment). +::: + +--- ## Prerequisites @@ -22,17 +56,17 @@ It authenticates users, enforces per-tool permissions through trust levels, and 3. Connect your Permit.io organization: - Go to [Permit.io Settings > API Keys](https://app.permit.io/settings/api-keys) - Create an **organization-scoped** API key - - Paste the key into the Agent Security platform + - Paste the key into the Permit MCP Gateway platform Once connected, your organization name appears in the sidebar. You can connect multiple organizations and switch between them from the sidebar menu. ## 2. Create a host -A **host** is a named instance of the Agent Security Gateway, with its own subdomain, policies, users, and sessions. Each host maps to a single Permit.io environment, and each environment can only be linked to one host. +A **host** is a named instance of the Permit MCP Gateway, with its own subdomain, policies, users, and sessions. Each host maps to a single Permit.io environment, and each environment can only be linked to one host. 1. Go to the [**Dashboard**](https://app.agent.security/) and select **Hosts**, then click **Create Host** 2. Fill in: - - **Subdomain** — choose a prefix (e.g., `my-tenant`). A unique suffix like `round-moccasin-19` is auto-generated. + - **Subdomain** — choose a prefix (e.g., `my-tenant`). A unique suffix like `brave-coral-37` is auto-generated. - **Project** — select the Permit project that contains the environment you want to use. - **Environment** — select the Permit environment this host will use. The environment cannot be changed after the host is created. 3. Click **Create Host** @@ -46,13 +80,15 @@ If you need a new Permit environment, select **+ Create new environment** from t Your gateway is now live at: ``` -https://acme-pink-panda-6942.agent.security/mcp +https://acme-brave-coral-37.agent.security/mcp ``` The host detail page shows the full MCP URL and ready-to-copy configuration snippets for MCP clients. ![Dashboard with Gateway MCP URL and client configuration snippets](/img/agent-security/dashboard.png) +**Expected result:** You have a live gateway URL. No one can access it yet because no MCP servers are imported and no users have been granted access. + ## 3. Import MCP servers The import flow connects to an upstream MCP server, discovers its tools, and creates the corresponding resources and permissions in Permit. @@ -73,6 +109,8 @@ The import flow connects to an upstream MCP server, discovers its tools, and cre ![Import MCP Server — review tools and trust levels](/img/agent-security/import-mcp-review.png) +**Expected result:** The MCP server and its tools appear on the MCP Servers page. Tools are classified into low, medium, and high trust levels. No users can access the server yet. + ### Edit an MCP server After import, manage the server from its detail page in [app.agent.security](https://app.agent.security): @@ -103,6 +141,8 @@ Granting user-level access is a step that's easy to overlook. If users report se ![Human user detail — MCP server access and connected agents](/img/agent-security/human-detail.png) +**Expected result:** The user now has permission to connect to the selected MCP servers. When they go through the consent flow, they will see those servers in the list. + When the user later completes the [consent flow](#7-user-consent-flow), they will see only the MCP servers they've been granted access to. ## 5. Manage agents and user permissions @@ -148,9 +188,9 @@ Add to `.cursor/mcp.json` (Cursor) or your VS Code MCP settings: ```json { "mcpServers": { - "agent-security": { + "permit-mcp-gateway": { "command": "npx", - "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"] + "args": ["-y", "mcp-remote", "https://acme-brave-coral-37.agent.security/mcp"] } } } @@ -166,9 +206,9 @@ Add to your Claude Desktop config file: ```json { "mcpServers": { - "agent-security": { + "permit-mcp-gateway": { "command": "npx", - "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"] + "args": ["-y", "mcp-remote", "https://acme-brave-coral-37.agent.security/mcp"] } } } @@ -177,7 +217,7 @@ Add to your Claude Desktop config file: ### Claude Code ```bash -claude mcp add agent-security --transport http https://acme-pink-panda-6942.agent.security/mcp +claude mcp add permit-mcp-gateway --transport http https://acme-brave-coral-37.agent.security/mcp ``` ### Pre-selected MCP server @@ -185,7 +225,7 @@ claude mcp add agent-security --transport http https://acme-pink-panda-6942.agen To link users directly to a specific MCP server, append the upstream URL as a query parameter: ``` -https://acme-pink-panda-6942.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp +https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp ``` The consent UI will have that MCP server pre-selected so the user can proceed directly to trust level selection. The user must still have been [granted access](#4-grant-user-access-to-mcp-servers) to the server by an admin. If the user has not been granted access to the specified server, it will not appear in the consent screen — the pre-selection parameter is ignored and the user sees only the servers they have access to. @@ -193,7 +233,7 @@ The consent UI will have that MCP server pre-selected so the user can proceed di Alternatively, use a **path-based URL** to route directly to a specific server by its key: ``` -https://acme-pink-panda-6942.agent.security/mcp/linear +https://acme-brave-coral-37.agent.security/mcp/linear ``` This bypasses the server selection step entirely — the consent flow still requires login and trust level selection, but the user connects directly to the specified server. @@ -256,7 +296,7 @@ The gateway currently returns **all tools** in `list_tools` responses, regardles Every authorization decision — allowed or denied — is recorded in two places: -- **Agent Security platform** ([app.agent.security](https://app.agent.security)) — the [**Humans**](https://app.agent.security/humans) page shows activity per user and the [**Agents**](https://app.agent.security/agents) page shows activity per agent, including every tool call and whether it was allowed or denied +- **Permit MCP Gateway dashboard** ([app.agent.security](https://app.agent.security)) — the [**Humans**](https://app.agent.security/humans) page shows activity per user and the [**Agents**](https://app.agent.security/agents) page shows activity per agent, including every tool call and whether it was allowed or denied - **Permit.io dashboard** ([app.permit.io](https://app.permit.io)) — the **Audit Log** page in the linked environment shows the same authorization decisions alongside your other Permit policy logs Each log entry includes the agent identity, the tool called, the MCP server targeted, and whether the request was allowed or denied. @@ -280,12 +320,12 @@ Tools that don't match any medium or high pattern default to **low** trust. The ## Troubleshooting :::warning Remove duplicate MCP server connections -If you have the same MCP server configured both through Agent Security **and** as a direct connection in your MCP client, your AI agent may bypass the gateway entirely. Always remove or disable direct MCP server connections for any server you've imported into Agent Security. See the first troubleshooting entry below. +If you have the same MCP server configured both through Permit MCP Gateway **and** as a direct connection in your MCP client, your AI agent may bypass the gateway entirely. Always remove or disable direct MCP server connections for any server you've imported into the gateway. See the first troubleshooting entry below. ::: | Symptom | Likely cause | Fix | | ------- | ------------ | --- | -| Agent bypasses permissions and performs actions that should be denied (e.g., deletes a resource despite medium trust level) | The same MCP server is installed both through the Agent Security gateway **and** directly in the MCP client. The AI agent may route calls through the direct connection, bypassing the gateway entirely. | Remove or disable the duplicate direct MCP server connection from your client configuration. Only the Agent Security gateway URL should remain. For example, if you imported Linear via Agent Security, remove any separate `mcp.linear.app` entry from your `.cursor/mcp.json` or Claude Desktop config. | +| Agent bypasses permissions and performs actions that should be denied (e.g., deletes a resource despite medium trust level) | The same MCP server is installed both through the gateway **and** directly in the MCP client. The AI agent may route calls through the direct connection, bypassing the gateway entirely. | Remove or disable the duplicate direct MCP server connection from your client configuration. Only the gateway URL should remain. For example, if you imported Linear via the gateway, remove any separate `mcp.linear.app` entry from your `.cursor/mcp.json` or Claude Desktop config. | | MCP client shows "host not found" | Gateway URL is incorrect or host doesn't exist | Verify the URL on the **Hosts** section of the [**Dashboard**](https://app.agent.security/) | | No MCP servers in the consent screen | Admin hasn't granted the user access to any servers | Grant the user access on the [**Humans**](https://app.agent.security/humans) page | | "Permission denied" on a tool call | Agent's trust level is too low for that tool | The user can re-consent with a higher trust level by disconnecting the MCP server in their client and reconnecting — the consent flow will run again, letting them choose a new trust level. Alternatively, the admin can adjust trust levels on the [**Agents**](https://app.agent.security/agents) page. | @@ -296,11 +336,11 @@ If you have the same MCP server configured both through Agent Security **and** a | Re-consent doesn't offer a higher trust level | The user's max trust level is too low | An admin must first increase the user's max trust level on the [**Humans**](https://app.agent.security/humans) page (see [Step 4](#4-grant-user-access-to-mcp-servers)) before the user re-consents | | Token expired errors | Session has expired | The user needs to reconnect — disconnect the MCP server in the client and reconnect. The [consent flow](#7-user-consent-flow) runs again, letting the user re-authenticate and confirm their trust level. | | `upstream_mcp` parameter used but server doesn't appear in consent | The user has not been granted access to that server | The pre-selection parameter is silently ignored when the user lacks access. Grant the user access on the [**Humans**](https://app.agent.security/humans) page (see [Step 4](#4-grant-user-access-to-mcp-servers)), then have them retry. | -| Can't find audit logs | Checking only one of the two log locations | Audit logs are available both in the Agent Security platform ([app.agent.security](https://app.agent.security)) on the Humans and Agents pages, and in the Permit.io dashboard ([app.permit.io](https://app.permit.io)) under Audit Log in the linked environment. See [Audit logs](#9-audit-logs) for details. | +| Can't find audit logs | Checking only one of the two log locations | Audit logs are available both in the Permit MCP Gateway dashboard ([app.agent.security](https://app.agent.security)) on the Humans and Agents pages, and in the Permit.io dashboard ([app.permit.io](https://app.permit.io)) under Audit Log in the linked environment. See [Audit logs](#9-audit-logs) for details. | ## Authentication methods -Each Agent Security Gateway host can be configured with its own authentication methods, controlling how users sign in to the consent flow. By default, **email/password** authentication is enabled. +Each gateway host can be configured with its own authentication methods, controlling how users sign in to the consent flow. By default, **email/password** authentication is enabled. Go to the host's **Authentication** settings in [app.agent.security](https://app.agent.security) to enable or disable methods. diff --git a/docs/permit-mcp-gateway/host-setup.mdx b/docs/permit-mcp-gateway/host-setup.mdx index a212ce7b..3829f193 100644 --- a/docs/permit-mcp-gateway/host-setup.mdx +++ b/docs/permit-mcp-gateway/host-setup.mdx @@ -1,17 +1,17 @@ --- title: "Guide: Setting Up Hosts for Your Organization" sidebar_label: Host Setup Guide -description: A step-by-step guide for organizations deploying Agent Security — from creating your first host to onboarding users at scale. +description: A step-by-step guide for organizations deploying Permit MCP Gateway — from creating your first host to onboarding users at scale, with rollout guidance. sidebar_position: 4.2 --- # Setting Up Hosts for Your Organization -This guide walks through deploying Agent Security for your organization — from creating your first host to onboarding your team and scaling to multiple environments. +This guide walks through deploying Permit MCP Gateway for your organization — from creating your first host to onboarding your team and scaling to multiple environments. ## What is a host? -A **host** is a named instance of the Agent Security Gateway. Each host gets its own subdomain (e.g., `acme-pink-panda-6942.agent.security`) and provides a complete, isolated security boundary: +A **host** is a named instance of the Permit MCP Gateway. Each host gets its own subdomain (e.g., `acme-brave-coral-37.agent.security`) and provides a complete, isolated security boundary: - **Own subdomain** — a unique gateway URL for MCP clients to connect to - **Own Permit environment** — policies, roles, and resource definitions are scoped to this host @@ -32,7 +32,7 @@ Connect the Permit.io organization you want to manage: 1. Go to [Permit.io Settings > API Keys](https://app.permit.io/settings/api-keys) 2. Create an **organization-scoped** API key -3. Paste the key into the Agent Security platform +3. Paste the key into the Permit MCP Gateway platform Once connected, your organization name appears in the header. You can connect multiple organizations and switch between them using the organization selector. @@ -40,7 +40,7 @@ Once connected, your organization name appears in the header. You can connect mu 1. Go to the **Dashboard** and click **Create Host** 2. Fill in: - - **Subdomain prefix** — choose a name that identifies the host's purpose (e.g., `acme`, `acme-staging`, `engineering`). A unique suffix like `pink-panda-6942` is auto-generated to ensure DNS uniqueness. + - **Subdomain prefix** — choose a name that identifies the host's purpose (e.g., `acme`, `acme-staging`, `engineering`). A unique suffix like `brave-coral-37` is auto-generated to ensure DNS uniqueness. - **Project** — select the Permit project that contains the environment you want to use - **Environment** — select the Permit environment this host will use. The environment cannot be changed after the host is created. 3. Click **Create Host** @@ -75,13 +75,15 @@ Import the upstream MCP servers your team needs access to: 3. If the server requires authentication, you'll be redirected to sign in with the upstream provider. If the provider doesn't support automatic client registration, enter OAuth credentials (Client ID / Secret) manually. -4. Review the discovered tools — each is auto-classified with a trust level: +4. Review the discovered tools — each is auto-classified with a trust level based on naming patterns: -| Trust level | Classification | Naming patterns | -| ----------- | -------------- | --------------- | -| **Low** | Read-only (default) | Tools not matching medium or high patterns | -| **Medium** | Write operations | `create`, `write`, `update`, `send`, `execute`, `deploy`, etc. | -| **High** | Destructive operations | `delete`, `remove`, `destroy`, `drop`, `purge`, etc. | +| Trust level | Classification | Examples | +| ----------- | -------------- | -------- | +| **Low** | Read-only (default) | `get_issues`, `list_repos`, `search_files` | +| **Medium** | Write operations | `create_issue`, `update_record`, `send_message` | +| **High** | Destructive operations | `delete_repo`, `remove_member`, `destroy_environment` | + + See the [trust level reference](/permit-mcp-gateway/guide#trust-level-reference) for the complete list of keyword patterns used for classification. 5. Override trust levels and enable/disable tools as needed, then click **Import** @@ -141,9 +143,9 @@ Give your users the gateway MCP URL. The Dashboard provides ready-to-copy snippe ```json { "mcpServers": { - "agent-security": { + "permit-mcp-gateway": { "command": "npx", - "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"] + "args": ["-y", "mcp-remote", "https://acme-brave-coral-37.agent.security/mcp"] } } } @@ -154,9 +156,9 @@ Give your users the gateway MCP URL. The Dashboard provides ready-to-copy snippe ```json { "mcpServers": { - "agent-security": { + "permit-mcp-gateway": { "command": "npx", - "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"] + "args": ["-y", "mcp-remote", "https://acme-brave-coral-37.agent.security/mcp"] } } } @@ -165,7 +167,7 @@ Give your users the gateway MCP URL. The Dashboard provides ready-to-copy snippe **Claude Code:** ```bash -claude mcp add agent-security --transport http https://acme-pink-panda-6942.agent.security/mcp +claude mcp add permit-mcp-gateway --transport http https://acme-brave-coral-37.agent.security/mcp ``` #### Pre-selected MCP server URLs @@ -173,7 +175,7 @@ claude mcp add agent-security --transport http https://acme-pink-panda-6942.agen To direct users to a specific MCP server, append the upstream URL as a query parameter: ``` -https://acme-pink-panda-6942.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp +https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp ``` The consent UI will have that server pre-selected, streamlining the setup for users. The user must still have been granted access to the server — if they haven't, the pre-selection is ignored. @@ -252,7 +254,7 @@ Domain restrictions can be set: ### Migrating from direct MCP server access -If your team is currently connecting MCP clients directly to upstream MCP servers (e.g., `https://mcp.linear.app/mcp`), you can migrate to the Agent Security Gateway with minimal disruption: +If your team is currently connecting MCP clients directly to upstream MCP servers (e.g., `https://mcp.linear.app/mcp`), you can migrate to Permit MCP Gateway with minimal disruption: 1. **Create a host** and import the same MCP servers your team is already using 2. **Review trust levels** — verify the auto-classified trust levels match your security requirements, and override where needed @@ -269,3 +271,52 @@ After migration, all tool calls flow through the gateway — giving you authenti :::tip Start with a small pilot group. Migrate a few users first, verify everything works, then roll out to the full team. You can keep direct MCP access running in parallel during the transition. ::: + +## Rollout Guidance + +Adopting Permit MCP Gateway incrementally reduces risk and builds organizational confidence. This section describes a recommended rollout approach. + +### Phase 1: Pilot (1–2 weeks) + +**Goal:** Validate that the gateway works with your MCP servers and clients, and that the setup matches your security requirements. + +1. **Create a single pilot host** linked to a non-production Permit environment +2. **Import 1–2 MCP servers** that your team already uses (e.g., GitHub, Linear) +3. **Grant access to 2–3 pilot users** at **low** (read-only) trust to start +4. **Have pilot users connect their MCP clients** through the gateway and complete the consent flow +5. **Review audit logs** — verify that tool calls are being logged correctly and that allowed/denied decisions match expectations +6. **Test trust level enforcement** — confirm that destructive operations are denied at low trust, and that raising trust to medium enables write operations + +**What to look for:** +- Are all expected tools discovered during import? +- Do trust level classifications match your security expectations? Override any that don't. +- Is the consent flow smooth for your authentication method (SSO, OAuth, email)? +- Are audit log entries clear and useful? + +### Phase 2: Controlled Expansion (2–4 weeks) + +**Goal:** Expand to more users and servers while keeping risk manageable. + +1. **Raise trust levels for pilot users** based on Phase 1 findings — move from low to medium where appropriate +2. **Import additional MCP servers** as needed +3. **Onboard a broader group of users** — pre-authorize by email and distribute the gateway URL +4. **Require consent/approval for sensitive tools** — keep destructive (high trust) tools restricted to specific users who need them +5. **Review audit logs regularly** — identify access patterns, unexpected denials, and any tools that need reclassification + +### Phase 3: Production Rollout + +**Goal:** Full team adoption with established security policies. + +1. **Create a production host** linked to a production Permit environment (if you used a staging environment for the pilot) +2. **Migrate users** — update MCP client configurations to point at the production gateway URL +3. **Remove direct MCP server connections** — ensure all MCP traffic flows through the gateway +4. **Configure SSO** (SAML/OIDC) and **domain restrictions** for enterprise authentication +5. **Set up monitoring** — establish a process for reviewing audit logs and responding to unexpected access patterns + +### Rollout Principles + +- **Start restrictive, then expand** — begin with low trust and raise incrementally based on observed behavior +- **Pilot before production** — use a separate staging host to validate configuration changes +- **Review before broadening** — inspect audit logs after each phase before adding more users or servers +- **Document trust level decisions** — record why specific tools were classified at specific levels, especially any manual overrides +- **Keep direct access disabled** — remove direct MCP server connections from client configs to prevent agents from bypassing the gateway diff --git a/docs/permit-mcp-gateway/index.mdx b/docs/permit-mcp-gateway/index.mdx index 87dbfc43..491287a4 100644 --- a/docs/permit-mcp-gateway/index.mdx +++ b/docs/permit-mcp-gateway/index.mdx @@ -1,44 +1,74 @@ --- title: Permit MCP Gateway sidebar_label: Permit MCP Gateway -description: Learn how Agent Security provides a robust permissions layer for Model Context Protocol (MCP) servers, ensuring secure and controlled access for AI agents +description: Permit MCP Gateway is a drop-in enforcement layer for MCP traffic — adding authentication, authorization, consent, and audit around existing MCP servers without code changes. --- -# Agent Security +# Permit MCP Gateway -Agent Security gives you visibility and control over what AI agents can do in your organization. It sits between your team's AI tools (like Cursor, Claude, and VS Code) and the services they connect to, enforcing who can access what, logging every action, and letting you set guardrails — all without changing your existing tools or code. +**Secure MCP access for developers and AI agents — without rewriting your tools.** -## Prerequisites +Permit MCP Gateway is a drop-in proxy between MCP clients (Cursor, Claude, VS Code, and other AI tools) and the MCP servers they connect to. It adds authentication, authorization, consent, and audit to every tool call — so your team can adopt MCP with identity-aware controls and full visibility from day one. -- A [Permit.io](https://app.permit.io) account (free tier available) -- Access to the [Agent Security Platform](https://app.agent.security) — the admin dashboard where you create hosts, import MCP servers, manage users, and monitor activity +No SDK. No agent rewrites. No changes to your MCP servers. Just a URL switch. + +--- + +## For Developers and Platform Teams -## What You Get +- **Set up in minutes** — create a host, import an MCP server, share the gateway URL +- **Works with existing MCP servers** — GitHub, Linear, Slack, Jira, and any server that speaks MCP +- **Copy-paste client configs** — ready-to-use snippets for Cursor, Claude Desktop, VS Code, and Claude Code +- **Predictable runtime** — allowed calls pass through transparently; denied calls return a clear error + +## For Security, IAM, and Governance Teams + +- **Identity-aware access control** — every tool call is tied to a specific human and agent identity +- **Least privilege by default** — tools classified by risk, admins set per-user trust ceilings +- **Consent-based delegation** — humans explicitly authorize agent access within admin-defined boundaries +- **Complete audit trail** — every decision logged with who, what, where, when, and allow/deny result +- **Deny by default** — no user or agent can access any tool until explicitly granted permission + +Read the [**Overview**](/permit-mcp-gateway/overview/) for the full explanation of how the gateway works, the security and trust model, and how it compares to existing tools. + +--- -- **Control what agents can do** — Set per-tool permissions with trust levels (read-only, write, destructive) so agents only access what they need -- **See everything agents do** — Every tool call is logged with who did it, what they did, and whether it was allowed -- **Enforce authentication** — Require SSO, OAuth, or other sign-in methods before agents can access tools -- **Human oversight** — Users choose what level of access to grant their agents through a consent flow +## Built on Permit.io + +Permit MCP Gateway is powered by [Permit.io](https://www.permit.io), which serves as the **control plane** and **default data plane** for every gateway instance. + +- Every gateway **host** maps 1:1 to a **Permit environment** — all policies, users, and audit data for that host live in the linked environment +- The full power of Permit's policy engine is available: RBAC, ABAC, ReBAC, real-time updates, and policy-as-code +- Two dashboards work together: **[app.permit.io](https://app.permit.io)** for policy management and audit analysis, **[app.agent.security](https://app.agent.security)** for gateway and MCP server management + +See [Permit.io Integration](/permit-mcp-gateway/permit-integration/) for the detailed policy model. + +--- ## Start Here -1. Read the [**Overview**](/permit-mcp-gateway/overview/) to understand what Agent Security is and how it works -2. Follow the [**Getting Started Guide**](/permit-mcp-gateway/guide/) to set up your first gateway in minutes +1. Read the [**Overview**](/permit-mcp-gateway/overview/) to understand what the gateway enforces and when to use it +2. Follow the [**Getting Started Guide**](/permit-mcp-gateway/guide/) to set up your first gateway and make your first authorized tool call ## Go Deeper -- [**Platform Reference**](/permit-mcp-gateway/platform/) — Admin UI guide for managing hosts, servers, and users +- [**Platform Reference**](/permit-mcp-gateway/platform/) — Admin UI for managing hosts, servers, and users - [**Humans & Agents**](/permit-mcp-gateway/managing-humans-and-agents/) — Managing users and the AI agents acting on their behalf -- [**Host Setup Guide**](/permit-mcp-gateway/host-setup/) — Multi-host patterns and onboarding users at scale +- [**Host Setup Guide**](/permit-mcp-gateway/host-setup/) — Multi-host patterns, onboarding at scale, and rollout guidance - [**Authentication Methods**](/permit-mcp-gateway/authentication-methods/) — SSO, OAuth, and sign-in configuration - [**Consent Service**](/permit-mcp-gateway/consent-service/) — The user consent journey in detail -- [**Audit Logs**](/permit-mcp-gateway/audit-logs/) — Reading and using activity logs -- [**Architecture Deep Dive**](/permit-mcp-gateway/architecture/) — Technical architecture, data flows, and sequence diagrams -- [**Permit.io Integration Deep Dive**](/permit-mcp-gateway/permit-integration/) — Policy engine internals and authorization model -- [**Advanced Features**](/permit-mcp-gateway/advanced-features/) — Enterprise capabilities: agent fingerprinting, shadow agent detection, HITL approvals, intent-based access control, permission receipts, and more +- [**Audit Logs**](/permit-mcp-gateway/audit-logs/) — Reading, filtering, and investigating activity logs +- [**Architecture**](/permit-mcp-gateway/architecture/) — Technical architecture, data flows, and sequence diagrams +- [**Permit.io Integration**](/permit-mcp-gateway/permit-integration/) — Policy engine internals and authorization model +- [**Advanced Features**](/permit-mcp-gateway/advanced-features/) — Enterprise capabilities and roadmap + +## Prerequisites + +- A [Permit.io](https://app.permit.io) account (free tier available) +- Access to the [Permit MCP Gateway admin dashboard](https://app.agent.security) where you create hosts, import MCP servers, manage users, and monitor activity -## Support and Resources +## Support - Join our [Slack Community](https://io.permit.io/slack) for discussions and updates - Access the [Permit.io API Reference](https://api.permit.io/v2/redoc) for the underlying authorization API -- Contact [Support](mailto:support@permit.io) for direct assistance +- Contact [support@permit.io](mailto:support@permit.io) for direct assistance diff --git a/docs/permit-mcp-gateway/managing-humans-and-agents.mdx b/docs/permit-mcp-gateway/managing-humans-and-agents.mdx index e860207b..71b9f514 100644 --- a/docs/permit-mcp-gateway/managing-humans-and-agents.mdx +++ b/docs/permit-mcp-gateway/managing-humans-and-agents.mdx @@ -1,13 +1,13 @@ --- title: Managing Humans and Agents sidebar_label: Humans & Agents -description: Understand the relationship between humans and agents in Agent Security — how trust flows, how identities work, and how to manage access for both. +description: Understand the relationship between humans and agents in Permit MCP Gateway — how trust flows, how identities work, and how to manage access for both. sidebar_position: 3.5 --- # Managing Humans and Agents -Agent Security introduces a distinct separation between **humans** (the people who authenticate) and **agents** (the MCP clients that act on their behalf). This guide explains the relationship model, how trust flows between them, and how to manage both in the [Platform](https://app.agent.security). +Permit MCP Gateway introduces a distinct separation between **humans** (the people who authenticate) and **agents** (the MCP clients that act on their behalf). This guide explains the relationship model, how trust flows between them, and how to manage both in the [admin dashboard](https://app.agent.security). ## Core Concepts diff --git a/docs/permit-mcp-gateway/overview.mdx b/docs/permit-mcp-gateway/overview.mdx index 5fcc44ca..c376902e 100644 --- a/docs/permit-mcp-gateway/overview.mdx +++ b/docs/permit-mcp-gateway/overview.mdx @@ -1,112 +1,253 @@ --- -title: Agent Security Overview +title: Overview sidebar_label: Overview -description: A comprehensive guide to Agent Security - the security gateway that provides identity-based access control, audit trails, and human-in-the-loop approvals for AI agent platforms. +description: How Permit MCP Gateway works — the enforcement proxy that adds authentication, authorization, consent, and audit to MCP server access for AI agents. sidebar_position: 1 --- -# Agent Security – The Permissions Gateway for Agentic AI Tools (MCPs) +# Permit MCP Gateway Overview -Agent Security is a security gateway that provides instant control and visibility over every Model Context Protocol (MCP) server interaction. With a single configuration change, it wraps AI agents' tool access in enterprise-grade security, offering identity-based access checks, comprehensive audit trails, and human-in-the-loop approvals—all without requiring SDKs or code changes. +Permit MCP Gateway is an enforcement proxy between MCP clients and MCP servers. It authenticates users, authorizes agent tool calls against fine-grained policy, collects explicit consent, and logs every decision — all without modifying your existing MCP servers or AI tools. :::info New to MCP? -The **Model Context Protocol (MCP)** is an open standard that lets AI tools connect to external services. MCP **clients** are the AI tools your team uses daily — Cursor, Claude Desktop, VS Code Copilot, Claude Code. MCP **servers** are the services they connect to — GitHub, Linear, Slack, Jira, and hundreds more. Agent Security sits between the two, giving you control over those connections. +The **Model Context Protocol (MCP)** is an open standard that lets AI tools connect to external services. MCP **clients** are AI tools like Cursor, Claude Desktop, VS Code, and Claude Code. MCP **servers** are the services they connect to — GitHub, Linear, Slack, Jira, and hundreds more. Permit MCP Gateway sits between the two, adding security controls to those connections. ::: -## The Challenge: Uncontrolled AI Agents and Invisible Risks +## The Problem -Enterprise adoption of agentic AI is surging, but security controls haven't kept pace. Teams deploy and consume MCP servers — the "USB-C for AI" that lets LLM agents plug into apps and data — without consistent oversight. Traditional API gateways and IAM tools were never designed for autonomous, context-driven agents. +Enterprise adoption of AI agents is accelerating, but security controls have not kept pace: -Organizations and CISOs face critical questions: -- Which AI agents are touching which systems? -- What data are they accessing? -- Who ultimately authorized those actions? +- **No visibility** — AI agents interact with production systems, but most organizations cannot answer basic questions: which agents are accessing which systems? What data are they reading or modifying? Who authorized those actions? +- **No per-tool control** — traditional API gateways and IAM tools were not designed for MCP. They do not model the human-to-agent delegation chain or provide per-tool access controls for autonomous agents. +- **Shadow MCP connections** — teams connect MCP servers in minutes, creating unvetted access paths to sensitive systems that bypass standard review. +- **Compliance gaps** — unchecked agent activity risks violating data-privacy regulations (GDPR, HIPAA) and weakening audit posture (SOC 2). When agents act on behalf of humans, regulators expect the same traceability that applies to human actions. +- **Privilege accumulation** — agents often run with overly broad access because there is no practical way to apply least privilege at the tool level. -## The Solution: Agent Security Gateway +## How Permit and Permit MCP Gateway Are Connected -Agent Security acts as a smart proxy between AI agents (MCP clients) and the tools or data they seek (MCP servers). It authenticates, authorizes, and audits every interaction, functioning as a zero-trust checkpoint for AI actions: +Permit MCP Gateway is built on top of [Permit.io](https://www.permit.io). Permit acts as the **control plane** and **default data plane** for every gateway instance — it is where policies are defined, authorization decisions are evaluated, and audit logs are stored. -1. **Authenticate** the originator (human) and the agent acting on their behalf -2. **Authorize** the requested action against fine-grained policy -3. **Audit** the outcome for compliance and threat-hunting +| Component | Role | Dashboard | +| --- | --- | --- | +| **Permit.io** | Control plane and policy engine. Manages the authorization model, evaluates every `permit.check()` call, and stores audit logs. | [app.permit.io](https://app.permit.io) | +| **Permit MCP Gateway** | Enforcement layer. Proxies MCP traffic, applies authentication and consent, and calls Permit for every authorization decision. The hosted SaaS gateway runs under `*.agent.security` subdomains. | [app.agent.security](https://app.agent.security) | -All this happens transparently — no modification to AI agents or MCP servers, just a URL switch. +### Every Host Is a Permit Environment + +Each gateway **host** (e.g., `acme-brave-coral-37.agent.security`) maps 1:1 to a **Permit environment**. This means: + +- **MCP servers** imported into a host become **resource types** in the linked Permit environment +- **Tools** become **actions** on those resources +- **Users and agents** are created as **Permit users** with role assignments in that environment +- **Trust levels** map to **Permit roles** with hierarchical permissions +- **Trust ceilings** are enforced using **Permit relations** and **derived roles** (ReBAC) + +Because the gateway builds on standard Permit primitives, you get the full power of Permit's policy engine: + +- **RBAC, ABAC, and ReBAC** policy models are all available +- **Real-time policy updates** via OPAL — changes to trust levels, access grants, or revocations take effect on the next tool call with no restart +- **Audit logs** for every authorization decision, accessible via the Permit dashboard and API +- **Policy-as-code** — policies can be managed via the Permit UI, API, or Terraform provider + +### Two Dashboards, One System + +You will work with two dashboards: + +- **[app.permit.io](https://app.permit.io)** — the Permit control plane. Use this for deep policy inspection, audit log analysis, viewing resource schemas, role assignments, and advanced policy configuration. This is where the authorization model lives. +- **[app.agent.security](https://app.agent.security)** — the gateway dashboard. Use this for day-to-day gateway management: creating hosts, importing MCP servers, granting user access, configuring authentication, and monitoring agent activity. + +Both dashboards show the same underlying authorization data. The gateway dashboard provides an MCP-focused view optimized for managing hosts, servers, and consent flows. The Permit dashboard provides the full policy view, including derived role rules, raw audit log entries, and resource schemas. + +For a detailed walkthrough of the policy model and how gateway concepts map to Permit primitives, see [Permit.io Integration](/permit-mcp-gateway/permit-integration/). + +--- + +## How the Gateway Works + +The gateway operates as a transparent proxy. Adopting it requires a single configuration change — pointing your MCP client at the gateway URL instead of directly at the upstream MCP server. + +### Setup (Admin) + +1. **Create a host** — a named gateway instance with its own subdomain, policies, and users +2. **Import MCP servers** — connect to upstream servers, discover their tools, and classify each tool by risk level +3. **Grant user access** — specify which users can connect to which MCP servers and set a per-user trust ceiling + +### Connection (User) + +4. **Connect and authenticate** — the MCP client connects to the gateway URL; the user signs in via the configured authentication method (SSO, OAuth, email) +5. **Consent** — the user selects an MCP server, reviews available tools, and chooses a trust level for their agent (up to the admin-defined ceiling) +6. **Use tools** — the MCP client operates normally; allowed tool calls pass through to the upstream server, and denied calls return a clear permission error + +### Runtime (Every Tool Call) + +7. **Authenticate** — the gateway verifies the agent's JWT and identifies the calling agent and its authorizing human +8. **Authorize** — the gateway checks Permit.io policy: *"Can this agent call this tool on this MCP server?"* +9. **Audit** — the authorization decision (allow or deny) is logged with full context: agent identity, human identity, tool name, MCP server, timestamp, and result + +All of this is transparent to the upstream MCP server, which receives proxied requests with the user's upstream credentials as usual. ## Key Capabilities -### Fine-Grained ReBAC, Identity-Based Access Control -- Combine user identity, agent identity, and resource scope in one policy -- Enforce true least-privilege down to individual MCP functions +### Authentication + +Users authenticate through the consent flow before any agent can access MCP servers. Each gateway host supports configurable authentication methods: -### Unified Policy Management -- One central policy layer instead of scattered configs -- Rules consistently apply to internal or third-party MCP servers +- Email/password, email OTP, passkeys +- Social OAuth (Google, GitHub, Microsoft) +- Enterprise SSO (SAML 2.0, OIDC) +- Domain restrictions and force-redirect for streamlined enterprise sign-in -### Complete Visibility & Auditing -- Real-time logs of every agent action with rich context -- Immediate traceability for incident response and compliance reporting +### Authorization -### Human-in-the-Loop Workflows -- Configurable step-up approvals for sensitive operations -- Optional but critical when AI touches high-risk data or funds +Every tool call is authorized in real time against fine-grained policy: -### Enterprise Integration -- Leverages existing SSO (OIDC, SAML) and social providers (Google, GitHub, Microsoft) -- Configurable per host with email domain restrictions and forced SSO redirect +- **Trust-level classification** — tools are auto-classified as low (read), medium (write), or high (destructive) during import, with manual overrides available +- **Per-user trust ceilings** — admins set the maximum trust level each user can grant their agents +- **Consent-based delegation** — users choose how much access to grant, within admin-defined boundaries +- **Relationship-based access control (ReBAC)** — authorization flows through a human → agent → server chain, enforced by Permit.io using a `min()` trust ceiling -### Zero-Code Deployment -- Works as a proxy; adopt by routing MCP traffic to the gateway -- Roll out governance in minutes, even across dozens of AI integrations +### Consent -### Compliance Assurance -- Enforce data-privacy rules (GDPR, HIPAA) and strengthen SOC 2 controls -- Stop unauthorized PII access or data exfiltration before it happens +A one-time consent flow ensures that humans explicitly authorize agent access: -## Current Security Risks & Compliance Gaps +- Users see which tools are available at each trust level before granting access +- Trust levels above the admin ceiling are disabled +- Consent is enforced at three layers: UI, API validation, and policy engine +- Sessions persist across client restarts, with configurable expiry (30-day inactivity / 90-day absolute) -1. **Lack of Visibility & Oversight** - - AI agents often act with powerful access yet leave no usable logs - - Makes malicious or mistaken actions hard to detect +### Audit -2. **Unauthorized Actions & Privilege Abuse** - - Over-permissive agents can delete data, transfer funds, or leak secrets - - Risks from error, prompt injection, or insider threat +Every authorization decision is logged automatically: -3. **Shadow IT in AI Form** - - Teams spin up MCP integrations in minutes - - Bypasses standard review and creates unvetted connections +- Logged in both the [Permit MCP Gateway dashboard](https://app.agent.security) and the [Permit.io dashboard](https://app.permit.io) +- Each entry includes: agent identity, human identity, tool name, MCP server, timestamp, and allow/deny decision +- Filterable by agent, user, server, action, or decision +- Supports compliance reporting, incident investigation, and access pattern analysis + +--- -4. **Compliance & Data-Privacy Violations** - - Unchecked agent activities risk breaching GDPR, HIPAA, and SOC 2 - - Particularly concerning for PII or regulated data access +## Security and Trust Model -5. **Operational Chaos & Security Drift** - - Manual processes can't keep pace with agent sprawl - - Leads to mismatched policies and difficulty in incident forensics +This section describes what Permit MCP Gateway enforces, what it logs, and what remains the responsibility of other components in your environment. -## How It Works +### What the Gateway Sees -1. **Admin** connects to [app.agent.security](https://app.agent.security) and creates a host linked to their Permit environment -2. **Admin** imports upstream MCP servers and defines the trust policy for each tool -3. **Admin** grants specific users permission to connect to specific MCP servers -4. **User** connects their MCP client (e.g., Cursor) to the gateway and signs in +| Data | Description | +| --- | --- | +| **User identity** | Authenticated via the consent flow (SSO, OAuth, email) | +| **Agent identity** | The MCP client (e.g., Cursor, Claude Desktop) identified by its OAuth client ID | +| **Tool calls** | The name and parameters of every `call_tool` request | +| **MCP server identity** | Which upstream server the call is destined for | +| **Authorization decisions** | Whether each tool call was allowed or denied, and why | -![Consent flow — sign in](/img/agent-security/consent-flow/login.png) +### What the Gateway Enforces + +- **Authentication** — users must sign in before any agent can access MCP servers +- **Authorization** — every tool call is checked against policy; denied calls are blocked before reaching the upstream server +- **Trust ceilings** — agents cannot exceed the trust level granted by the human, and humans cannot exceed the ceiling set by the admin +- **Consent** — agents only receive access after the human completes the consent flow +- **Session management** — sessions expire after inactivity or absolute time limits, and can be revoked immediately by admins + +### What the Gateway Logs + +- Every `call_tool` authorization decision (allow or deny) with full context +- User sign-in and consent events +- Agent-to-server session creation and expiry +- All logs are available via the Permit MCP Gateway dashboard and the Permit.io audit log API + +### Hosted vs. Customer-Controlled Deployment + +| Aspect | Hosted | Customer-Controlled | +| --- | --- | --- | +| **Gateway location** | Managed by Permit at `*.agent.security` | Runs in your environment (VPC, on-prem) | +| **Policy decisions** | Evaluated by Permit.io cloud PDP | Can be evaluated by a local PDP | +| **Data in transit** | MCP traffic flows through the hosted gateway | MCP traffic stays within your network | +| **Best for** | Fast adoption, SaaS workloads, evaluation | Regulated environments, data residency requirements | + +:::note +Customer-controlled deployment is available for enterprise plans. [Contact us](mailto:support@permit.io) for architecture details. The hosted deployment is available for all plans and is the recommended starting point. +::: -5. **User** picks an MCP server from their allowed list, chooses a trust level, and consents +### What Risks the Gateway Mitigates -![Consent flow — select MCP server](/img/agent-security/consent-flow/select-server.png) +- **Unauthorized tool access** — agents can only call tools they are explicitly permitted to use +- **Privilege escalation** — the `min()` trust ceiling prevents agents from exceeding admin-defined boundaries +- **Invisible agent activity** — every tool call is logged and traceable to a specific human and agent +- **Unvetted MCP connections** — by default, users can only connect to admin-approved MCP servers +- **Credential exposure to agents** — upstream OAuth tokens are managed by the gateway, not exposed to MCP clients -![Consent flow — set trust level and review tools](/img/agent-security/consent-flow/trust-level-slider.png) +### What the Gateway Does Not Fully Solve -6. **Gateway** enforces per-tool authorization on every call — denied actions return a permissions error -7. **Admin** monitors all activity on the Humans and Agents pages in [app.agent.security](https://app.agent.security) +The gateway enforces access control and audit at the MCP protocol layer. These areas remain the responsibility of the surrounding environment: + +- **Upstream server security** — the gateway does not validate what the upstream MCP server does with authorized requests. Server-side input validation, data access controls, and business logic remain the server's responsibility. +- **Prompt injection and adversarial inputs** — the gateway authorizes tool calls based on identity and policy, not on the content or intent of prompts. Defending against prompt injection is the responsibility of the MCP client and LLM layer. +- **Data classification** — the gateway classifies tools by risk level (read/write/destructive) based on naming patterns. It does not inspect the data returned by tool calls or classify data sensitivity. +- **Network-level controls** — the gateway operates at the application layer. Network segmentation, firewall rules, and transport security for upstream connections are managed separately. + +--- + +## How It Compares to Existing Tools + +| Approach | Limitation for MCP use cases | +| --- | --- | +| **API gateways** (Kong, Apigee, etc.) | Designed for REST/gRPC APIs, not MCP protocol. No model of human-to-agent delegation or per-tool trust levels. | +| **IAM platforms** (Okta, Azure AD, etc.) | Handle user authentication but do not enforce per-tool authorization for autonomous agents or model consent-based delegation. | +| **Manual MCP server access** | No authentication, no authorization, no audit. Agents connect directly with whatever credentials are available. | +| **Permit MCP Gateway** | Purpose-built for MCP: identity-aware per-tool authorization, human-to-agent trust delegation, consent, and audit in one enforcement point. | --- -Agent Security delivers the visibility and control you need to safely enable AI innovation. The centralized gateway enforces policy, logs actions, and ensures compliance — all with minimal setup. +## Use Cases + +### Securely Consume MCP Servers (Internal) + +Your team uses Cursor, Claude, VS Code, or internal agents to interact with MCP servers like GitHub, Linear, Slack, and Jira. Permit MCP Gateway sits between your agents and those servers, enforcing per-user access control, trust-level policies, and logging every tool call. + +**Typical scenario:** An engineering team connects Cursor to GitHub and Linear through the gateway. Admins grant developers read/write access but restrict destructive operations. Every tool call is logged, and new MCP servers require admin approval before anyone can connect. + +### Provide Secure MCP Servers to Customers + +You build or host MCP servers that your customers connect to. Permit MCP Gateway adds authentication, per-customer authorization, consent, and audit — so each customer's agents only access what they are permitted to, with full traceability. + +**Typical scenario:** A SaaS platform exposes its API as an MCP server. Enterprise customers connect their AI agents through the gateway with SSO, per-user trust levels, and isolated audit trails per customer. + +--- + +## When to Use Permit MCP Gateway + +Permit MCP Gateway is especially valuable when: + +- You already use or plan to use MCP from tools like Cursor, Claude, VS Code, or internal agents +- You need per-user or per-agent controls over which tools can be called +- You need a central audit trail of all agent actions across MCP servers +- You want consent or approval workflows for sensitive operations +- You do not want every MCP server trusted equally — different servers and tools need different risk controls +- You are building MCP servers to be consumed securely by your customers +- You want to enable enterprise workflows where agents interact with sensitive systems or data + +If you are not yet using MCP, or if your agents do not interact with external tools or data, you may not need the gateway today — but it is designed to be adopted incrementally as your MCP usage grows. + +--- + +## Deployment Options + +### Hosted Gateway (SaaS) + +The fastest way to get started. Each gateway host runs under a subdomain of `agent.security` (e.g., `acme-brave-coral-37.agent.security`), with TLS, session management, and audit logging included. Permit.io provides both the control plane ([app.permit.io](https://app.permit.io)) and the hosted data plane (PDP) that evaluates authorization decisions. + +- **No infrastructure to manage** — Permit hosts the gateway, consent service, and policy decision point +- **Minutes to first value** — create a host, import a server, connect a client +- **Isolated per host** — each host gets its own subdomain, users, policies, and sessions + +### Customer-Controlled Deployment + +For organizations that require enforcement within their own network boundary, Permit offers deployment options where the gateway and policy decision point (PDP) run in your environment. Permit.io still serves as the control plane, but authorization decisions and MCP traffic stay within your network. + +:::note +Customer-controlled deployment is available for enterprise plans. [Contact us](mailto:support@permit.io) or [schedule a demo](https://calendly.com/permit-io/demo) for architecture details and availability. +::: + +--- -Ready to secure your AI operations? Get in touch: -- Email us at [support@permit.io](mailto:support@permit.io) -- Join our [Slack community](https://io.permit.io/slack) -- Schedule a [demo](https://calendly.com/permit-io/demo) +Ready to get started? Follow the [Getting Started Guide](/permit-mcp-gateway/guide/) to set up your first gateway in minutes. diff --git a/docs/permit-mcp-gateway/permit-integration.mdx b/docs/permit-mcp-gateway/permit-integration.mdx index 770c94dc..5070372b 100644 --- a/docs/permit-mcp-gateway/permit-integration.mdx +++ b/docs/permit-mcp-gateway/permit-integration.mdx @@ -1,35 +1,56 @@ --- -title: How Agent Security Works with Permit.io -sidebar_label: Permit.io Integration Deep Dive -description: Understand the deep integration between Agent Security and Permit.io — the policy engine, authorization model, sync flow, and dashboard tools that power every tool-call decision. +title: How Permit MCP Gateway Works with Permit.io +sidebar_label: Permit.io Integration +description: Understand the deep integration between Permit MCP Gateway and Permit.io — the policy engine, authorization model, sync flow, and dashboard tools that power every tool-call decision. sidebar_position: 8 --- -# How Agent Security Works with Permit.io +# How Permit MCP Gateway Works with Permit.io -Agent Security uses [Permit.io](https://www.permit.io) as its **policy engine** — every authorization decision for every tool call is evaluated by Permit. This isn't a loose integration; Permit is the core of how permissions are modeled, enforced, and audited. +Permit MCP Gateway uses [Permit.io](https://www.permit.io) as its **control plane** and **default data plane**. Permit is not a peripheral integration — it is the core of how permissions are modeled, enforced, and audited. Every authorization decision for every tool call is evaluated by Permit. This page explains **why** Permit is central, **how** the policy model maps to Permit primitives, **what** happens during each sync step, and **where** to find everything in the Permit dashboard. +## The Relationship Between Permit and the Gateway + +Permit.io and Permit MCP Gateway form a single system with two dashboards: + +| | Permit.io | Permit MCP Gateway | +| --- | --- | --- | +| **Role** | Control plane and policy engine | Enforcement layer and MCP proxy | +| **Dashboard** | [app.permit.io](https://app.permit.io) | [app.agent.security](https://app.agent.security) | +| **What it manages** | Authorization model, policy evaluation (PDP), audit logs, resource schemas, role assignments | Hosts, MCP server imports, user consent, authentication, session management | +| **What it stores** | Policies, users, roles, relations, derived roles, audit log entries | Host configurations, sessions, upstream OAuth tokens | + +**Every gateway host maps to a Permit environment.** When an admin creates a host and selects a Permit project and environment, that environment becomes the host's authorization boundary. All resources, users, roles, and audit logs for that host live in the linked Permit environment. + +Because the gateway builds on standard Permit primitives, you get the full power of Permit's policy engine through this connection: + +- **RBAC, ABAC, and ReBAC** policy models +- **Real-time policy updates** via OPAL — changes take effect on the next tool call with no restart +- **Complete audit trail** — every `permit.check()` call is logged +- **Policy-as-code** — policies manageable via the Permit UI, API, or Terraform provider +- **Local PDP option** — for customer-controlled deployments, the PDP can run in your environment so authorization decisions stay within your network + ## Why Permit.io? -Agent Security needs a policy engine that can: +Permit MCP Gateway needs a policy engine that can: - **Evaluate fine-grained, relationship-based access control (ReBAC)** — decisions depend on who the user is, which agent is acting, and which MCP server and tool are involved - **Apply changes instantly** — when an admin adjusts a trust level or revokes access, the change takes effect on the next tool call with no restart or redeployment - **Provide a full audit trail** — every `permit.check()` call is logged, giving complete visibility into what was allowed or denied and why -Permit.io provides all three. Agent Security builds its authorization model using Permit's resource types, actions, roles, relations, and derived roles — and the Permit PDP (Policy Decision Point) evaluates every tool call in real time. +Permit.io provides all three. Permit MCP Gateway builds its authorization model using Permit's resource types, actions, roles, relations, and derived roles — and the Permit PDP (Policy Decision Point) evaluates every tool call in real time. ## The Policy Model -Agent Security maps its concepts directly to Permit primitives. Understanding this mapping is the key to understanding how authorization works. +Permit MCP Gateway maps its concepts directly to Permit primitives. Understanding this mapping is the key to understanding how authorization works. ### Resources and Actions Each imported MCP server becomes a **resource type** in Permit. The server's tools become **actions** on that resource type. -| Agent Security concept | Permit primitive | Example | +| Gateway concept | Permit primitive | Example | | --- | --- | --- | | MCP server | Resource type | `linear` | | MCP server instance | Resource instance | `linear:linear` (type and instance share the same key) | @@ -230,15 +251,15 @@ Each component owns specific Permit operations: ## Using the Permit Dashboard -Since Agent Security builds on standard Permit primitives, you can inspect and debug everything from the [Permit dashboard](https://app.permit.io). +Since Permit MCP Gateway builds on standard Permit primitives, you can inspect and debug everything from the [Permit dashboard](https://app.permit.io). ### Finding Your Environment -Each Agent Security [host](/permit-mcp-gateway/guide#2-create-a-host) is linked to a specific Permit project and environment. To find it: +Each Permit MCP Gateway [host](/permit-mcp-gateway/guide#2-create-a-host) is linked to a specific Permit project and environment. To find it: 1. Log in to [app.permit.io](https://app.permit.io) 2. Select the project and environment that matches your host's configuration -3. The environment name typically matches the host name you set in Agent Security +3. The environment name typically matches the host name you set in the Permit MCP Gateway dashboard ### Viewing the Schema @@ -258,7 +279,7 @@ Every `permit.check()` call is logged by Permit. Use the **Audit Log** in the Pe - **Monitor tool-call patterns** — identify which tools are most used, which agents are most active, and whether any unexpected denials are occurring :::tip -The Permit audit log shows the raw `permit.check()` parameters — user key, action, and resource — making it easy to correlate with the [Agent Security audit logs](/permit-mcp-gateway/guide#9-audit-logs) visible in [app.agent.security](https://app.agent.security). +The Permit audit log shows the raw `permit.check()` parameters — user key, action, and resource — making it easy to correlate with the [Permit MCP Gateway audit logs](/permit-mcp-gateway/guide#9-audit-logs) visible in [app.agent.security](https://app.agent.security). ::: ## Server Metadata and Allow-List @@ -298,7 +319,7 @@ The `default` tenant is automatically created in Permit environments and require ## Default Policy: Deny by Default -A fresh Agent Security environment starts with **zero permissions**. No user or agent can call any tool until the full setup sequence is completed: +A fresh Permit MCP Gateway environment starts with **zero permissions**. No user or agent can call any tool until the full setup sequence is completed: 1. **Admin imports an MCP server** → creates resource type, actions, and instance in Permit 2. **Admin grants a human access** → creates the profile-to-server relation (sets the max trust ceiling) @@ -334,4 +355,4 @@ When an MCP server is imported, tools are auto-classified by naming heuristics ( - **Changes are instant** — update a trust level or revoke access in Permit, and the next tool call reflects it - **The `user_profile` indirection** is the core pattern — it enables the `min()` ceiling logic that separates admin control from user consent - **Three components, clear boundaries** — Platform writes policy, Consent Service writes agent roles, Gateway reads policy -- **Full auditability** — every decision is logged in both Agent Security and Permit +- **Full auditability** — every decision is logged in both Permit MCP Gateway and Permit.io diff --git a/docs/permit-mcp-gateway/platform.mdx b/docs/permit-mcp-gateway/platform.mdx index a873e4e0..fccb60ac 100644 --- a/docs/permit-mcp-gateway/platform.mdx +++ b/docs/permit-mcp-gateway/platform.mdx @@ -1,13 +1,13 @@ --- -title: Platform Service +title: Platform Reference sidebar_label: Platform -description: Reference guide for the Agent Security Platform — the admin UI for managing hosts, MCP servers, users, agents, and authentication settings. +description: Reference guide for the Permit MCP Gateway admin dashboard — the UI for managing hosts, MCP servers, users, agents, and authentication settings. sidebar_position: 3 --- -# Platform Service +# Platform Reference -The Agent Security Platform at [app.agent.security](https://app.agent.security) is the admin interface for configuring and managing your Agent Security deployment. From the platform you can create hosts, import MCP servers, manage user and agent permissions, and configure authentication settings. +The Permit MCP Gateway admin dashboard at [app.agent.security](https://app.agent.security) is the admin interface for configuring and managing your gateway deployment. From the dashboard you can create hosts, import MCP servers, manage user and agent permissions, and configure authentication settings. ## Prerequisites @@ -44,13 +44,13 @@ To connect a new organization: ## Hosts management -A **host** is a named instance of the Agent Security Gateway with its own subdomain, policies, users, and sessions. Each host maps to a single Permit.io environment, and each environment can only be linked to one host. +A **host** is a named instance of Permit MCP Gateway with its own subdomain, policies, users, and sessions. Each host maps to a single Permit.io environment, and each environment can only be linked to one host. ### Creating a host 1. Go to the **Dashboard** and click **Create Host** 2. Fill in: - - **Subdomain prefix** — e.g., `acme` (a unique suffix like `pink-panda-6942` is auto-generated) + - **Subdomain prefix** — e.g., `acme` (a unique suffix like `brave-coral-37` is auto-generated) - **Project** — select the Permit project that contains the environment you want to use - **Environment** — select the Permit environment this host will use. The environment cannot be changed after the host is created. 3. Click **Create Host** @@ -117,7 +117,7 @@ The import flow connects to an upstream MCP server, discovers its tools, and cre ### Tool auto-discovery and trust level classification -During import, Agent Security discovers all tools exposed by the upstream MCP server and automatically classifies each into a trust level: +During import, the gateway discovers all tools exposed by the upstream MCP server and automatically classifies each into a trust level: | Trust level | Classification | Naming patterns | | ----------- | -------------- | --------------- |