Rebrand MCP Permissions docs to Agent Security + content & styling improvements#610
Merged
EliMoshkovich merged 47 commits intomasterfrom Mar 12, 2026
Conversation
Updated titles, descriptions, and content across multiple files to reflect the rebranding from MCPermit to Agent Security. Enhanced clarity on the architecture, setup, and core concepts of the Agent Security framework, ensuring consistency in terminology and improving user guidance for implementation.
✅ Deploy Preview for permitio-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Pull request overview
Refactors the MCP Permissions documentation to consistently use the new “Agent Security” terminology and updates content to better explain the product’s architecture, setup, and concepts.
Changes:
- Renamed MCPermit/MCP Permissions terminology to Agent Security across docs pages.
- Reworked “Getting Started” guide to match the hosted gateway flow (hosts, imports, consent, trust levels).
- Updated architecture docs to reflect trust-level authorization model and “coming soon” features.
Reviewed changes
Copilot reviewed 4 out of 6 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| docs/ai-security/mcp-permissions/overview.mdx | Rebrands overview page and aligns messaging with Agent Security terminology/capabilities. |
| docs/ai-security/mcp-permissions/index.mdx | Updates section landing page titles/labels/links and refreshes core concept bullets. |
| docs/ai-security/mcp-permissions/guide.mdx | Replaces prior MCPermit user guide with an Agent Security hosted setup + consent + trust-level walkthrough. |
| docs/ai-security/mcp-permissions/architecture.mdx | Updates architecture narrative/diagrams to match Agent Security gateway + trust-level auth model and roadmap. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
Reflect the new platform flow where admins explicitly grant users access to MCP servers, users pick from a list during consent, and audit logs live in app.agent.security. Add authentication methods reference section covering email, social, passkey, SAML, and OIDC.
Contributor
|
Need to add:
|
…cumentation for MCP permissions to clarify hosted gateway URL and enhance resource mapping details.
…rify hosted gateway URL and refine trust level classification details.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 6 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…mentation. Update instructions on granting access, pre-authorization, and trust levels to enhance user understanding of the consent flow and permissions.
…rflow and adding padding for multi-line text.
…arity on API key usage, host definitions, and user consent flow. Update terminology for user permissions and trust levels to improve understanding of the setup process.
…descriptions of the proxy/gateway role, trust level classifications, and deployment options. Update terminology for clarity and include upcoming features for human-in-the-loop approvals.
…ol point for authorization, audit, and anomaly detection is planned. This change enhances clarity regarding future capabilities in the MCP permissions architecture.
…y adjusting the fill and opacity properties for better visibility.
…nt sections in the Dashboard, MCP Servers, and Humans pages. This enhances navigation and clarity for users managing hosts, servers, and user permissions.
…cations, refining deployment options, and adding a new `user_profile` resource for relationship-based permission derivation. Clarify examples and terminology for better understanding of agent roles and permissions.
…ss by adding theme variables for edge labels and improving background color handling for better visibility in flowcharts and sequence diagrams.
CarlosMion
changed the title
Contributor
|
@EliMoshkovich My latest commit addresses your previous comments |
- Replace "Core Components" with full system architecture diagram showing all components: Platform UI, Consent Service, Gateway, Permit.io Cloud, PDP, PostgreSQL, Redis, and upstream MCP servers - Update admin setup sequence to route through Platform UI instead of directly to Gateway: Admin → Platform → Gateway/Permit - Add Platform UI and Permit.io as participants in first-time connection sequence diagram - Remove Embedded WASM / Remote PDP deployment table (Permit PDP internals, not Agent Security deployment options) Resolves: PER-14105 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Contributor
|
Blocker — Broken link (architecture.mdx line 123) Warning — user_profile:subject placeholder (architecture.mdx line 128) Warning — "consent service issues a JWT" (architecture.mdx line 151) |
The guide incorrectly implied OR semantics for domain restrictions. Actual behavior is intersection: a domain must be allowed by BOTH the global list AND the method-specific list. Added warning example showing that per-method domains do not bypass the global list. Resolves: PER-14104 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Clarify API reference link as "Permit.io API Reference" instead of implying it is an Agent Security-specific API - Add one-sentence description of what Agent Security does - Add prerequisites section (Permit.io account + Platform access) - Add link to Platform UI at app.agent.security Resolves: PER-14106 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
description in architecture.mdx - Replace broken permit-integration link with internal anchor to trust ceiling section - Correct user_profile instance key from :subject to :user_id (| not allowed in Permit keys) - Clarify JWT issuance as two-step code exchange to match sequence diagram
… PER-14116 per-14119 PER-14118 Agent Security Docs Phase 2: Architecture diagrams, platform guides, and Permit integration (#612) * PER 14120,14114,14117 * PER-14110,14111,14112 * Add Phase 2 docs: architecture diagrams, audit logs, permit integration, consent service, auth methods, on-prem deployment - PER-14120: Add 7 Mermaid diagrams to architecture.mdx (system overview, data flow, admin setup, consent flow with upstream OAuth, authorization decision flow, trust ceiling) - PER-14112: Expand permit-integration.mdx with derived role breakdown, allow-list enforcement, tenant model, default policy, customization guide - PER-14118: Add dedicated audit-logs.mdx page (screenshots pending) - Add consent-service.mdx, authentication-methods.mdx, on-prem-deployment.mdx - Add consent flow screenshots - Update guide.mdx and sidebars.js * added audit log screenshots for PER-14118 * fix: correct technical inaccuracies in Agent Security docs Critical fixes: - C4: Fix Permit API endpoint /v2/api/tokens/scope → /v2/api-key/scope in architecture.mdx sequence diagram - C5: Fix Redis key pattern host:{subdomain} → host_lookup:{subdomain} in two architecture.mdx sequence diagrams - C1/C2/C3: Rewrite session expiry in consent-service.mdx — 90-day TTL is a rolling inactivity timeout (not absolute), remove non-existent 30-day soft expiry, clarify these are MCP session TTLs not consent TTLs Important fixes: - I1: Add "(coming soon)" to HITL mentions in overview.mdx (meta + body) - I2: Add missing NGINX routes (/api/consent/*, /api/mcp/*) to data flow table - I3: Add "common pitfall" warning about granting user access in guide.mdx - M1: Add explanation of mcp-remote tool in client config section - M3: Clarify OPA/OPAL are used under the hood by Permit.io PDP Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: correct MCP error code and clarify consent service wording - architecture.mdx: permission denied error code is -32004, not -32001 (-32001 is UNAUTHORIZED for missing/invalid tokens) - consent-service.mdx: clarify that the profile-to-server relation is set by the admin and verified as a trust ceiling, not "confirmed" Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: improve customer-friendliness and remove on-prem page - Rewrite index.mdx: lead with outcomes instead of jargon (ReBAC, OPA, OPAL), organize navigation into "Start Here" and "Go Deeper" tiers - Add "New to MCP?" callout in overview.mdx for non-AI-expert readers - Reorder sidebar: Getting Started moved up to position 2, Architecture and Permit Integration moved to bottom as deep-dive reference - Relabel Architecture → "Architecture Deep Dive" and Permit.io Integration → "Permit.io Integration Deep Dive" - Remove on-prem-deployment.mdx (not ready for publication) - Remove on-prem references and deployment table from architecture.mdx - Update sidebars.js to match new page order Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: eli <eli@permit.io> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
…#611) * Update consent flow documentation and add new screenshots - Revise consent flow steps in the guide and overview documents to reflect updated user experience. - Introduce new images for sign-in, server selection, trust level setting, OAuth redirect, and processing consent. - Add an empty state screenshot for users without server access. This enhances clarity and visual guidance for users navigating the MCP client connection process. * Add Advanced Features page for Agent Security Introduces a new documentation page showcasing six advanced capabilities (fingerprinting, snitch skills, shadow agent detection, HITL, workflow intents, and time-limited consent) with Mermaid diagrams and status badges. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * Add troubleshooting guidance for duplicate MCP server connections Introduces a warning about the potential issues caused by having the same MCP server configured through both Agent Security and as a direct connection. Clarifies that this can lead to the AI agent bypassing the gateway, and provides a specific fix to remove or disable the duplicate connection. * Remove orphaned consent flow images Delete 3 unreferenced images replaced by new consent-flow screenshots. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: correct TTL descriptions and soften roadmap language in advanced-features - C1/C2/C3: Rewrite Time-Limited Consent section to accurately describe 90-day rolling inactivity TTL (not absolute), clarify soft TTL is not yet implemented, and distinguish MCP session TTLs from consent permissions - M4: Soften "coming soon" feature descriptions to avoid setting concrete expectations for unimplemented features Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: eli <eli@permit.io>
- Delete orphaned advanced-features.mdx (not in sidebar, not linked) - Change "Cloud or On-Prem" to "Cloud" in architecture diagram - Change "on-prem AI" to "co-located AI" in integration patterns table Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…oken refresh docs - Align host creation steps in platform.mdx, host-setup.mdx, and architecture.mdx to match actual UI (Project + Environment dropdowns instead of Permit API Key field) - Document both session TTLs accurately: soft 30-day inactivity TTL and hard 90-day absolute TTL (was incorrectly showing only 90-day inactivity) - Fix tools display description in consent-service.mdx to match actual UI (flat list with dynamic Allowed/Denied badges, not grouped by trust level) - Add upstream token auto-refresh note to the getting started guide - Fix mislabeled session type in consent-service.mdx info box Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Introduced a new documentation page for Advanced Features, detailing capabilities such as agent fingerprinting, shadow agent detection, and human-in-the-loop approvals. - Updated the sidebar to include a link to the new Advanced Features page, enhancing navigation for users seeking information on upcoming functionalities.
…mable diagrams, rename section - Add Enterprise-only callout banner to Advanced Features page - Remove all "coming soon" content from overview, architecture, and advanced features - Remove Roadmap table and Planned Policy Enhancements section from architecture - Create ZoomableDiagram component for click-to-expand Mermaid diagrams - Move MCP Permissions from AI Security to top-level "Permit MCP Gateway" section - Update all internal cross-references and add redirects for old URLs Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Render mermaid SVG at 1800px width in overlay for real zoom effect - Make overlay use full 95vw/90vh with scroll for pan navigation - Change hint from absolute-positioned to flow layout to avoid overlapping heading - Prevent body scroll when overlay is open Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add overflow:visible fix for mermaid edgeLabel foreignObject elements - Split long edge label "/mcp, /oauth/*, /.well-known/*" with line break to prevent mermaid from miscalculating the label container size Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Hide all unreleased feature sections (Agent Fingerprints, Snitch Skills, Shadow Agent Detection, HITL, Workflow Intent) inside MDX comments so they're preserved for future use but invisible to readers - Keep only Time-Limited Consent which is partially available today - Clean up Time-Limited Consent description (remove "future releases" language) - Update index.mdx link description to match Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remind future editors to review and update the content against the actual implementation before uncommenting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Uncomment all previously hidden feature sections — Agent Fingerprints, Snitch Skills, Shadow Agent Detection, HITL, and Workflow Intent Descriptions are now implemented. Enterprise-only banner remains. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…havior, sidebar ordering
- Fix OAuth discovery sequence diagram to route /.well-known/oauth-authorization-server to Gateway (not Consent Service)
- Document Dynamic MCPs feature (architecture, consent-service, permit-integration)
- Fix absolute server allow-list statement to account for dynamic MCPs opt-in
- Document /mcp/{static_mcp_key} path-based server selection
- Document list_tools visibility behavior (all tools visible, enforcement at call_tool)
- Fix Time-Limited Consent framing to distinguish built-in session expiry from Enterprise configurable windows
- Fix Policy-as-code claim (remove misleading Rego/GitOps/unit tests reference)
- Fix sidebar position conflicts (host-setup: 4→4.2, advanced-features: 4→9)
- Use realistic subdomain in architecture Redis key diagram
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…lear labels Rewrite to be a scannable overview with an `Enterprise` badge on each feature. Remove detailed mermaid diagrams, lengthy explanations, and use cases. Keep each section to 2-3 sentences describing what the feature does. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ceipts - Rename "Agent Fingerprints via Interrogation" → "Agent Fingerprinting" - Rename "Workflow Intent Descriptions" → "Intent-Based Access Control" - Add "Permission Receipts" Enterprise feature - Keep "Inject Security Snitch Skills" and "HITL" (future features) - Keep "Enterprise" tier labeling (source of truth over mock-ui "Pro") - Update index page reference Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Rename "Inject Security Snitch Skills" → "In-Session Monitoring" (clearer) - Remove raw `Enterprise` code-block badges (redundant with top banner) - Soften banner from :::caution to :::note (upsell, not warning) - Simplify descriptions — focus on customer value, remove jargon - Polish CTA section at bottom Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add value-prop intro sentence before features - Simplify Enterprise banner with single CTA (schedule demo) - Condense session expiry info callout - Strengthen bottom CTA with clear primary action Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Dynamic MCPs was only documented in the Architecture Deep Dive — too buried for customers to find. Now documented in: - Getting Started guide (after "Edit an MCP server", step 3) - Platform page (Settings section, before Authentication methods) Both link to the Architecture page for deeper technical details. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Platform page: trim to one-liner + link to guide - Architecture page: trim to Permit-specific detail + link to guide - Getting Started guide remains the authoritative section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The toggle lives in host Settings, so Platform is the natural home. All other pages now link to Platform#dynamic-mcps instead of duplicating content or linking to Architecture. - platform.mdx: full instructions, toggle behavior, warning - guide.mdx: tip callout + link to Platform - architecture.mdx: Permit-specific detail + link to Platform - consent-service.mdx: updated link to Platform - permit-integration.mdx: updated link to Platform Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EliMoshkovich
deleted the
dan/per-13548-agentsecurity-write-docs-for-agentsecurity
branch
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Rebrand MCP Permissions docs to Agent Security + content & styling improvements
Terminology rebrand
Agent Security across titles, headings, and body content in
architecture.mdx, guide.mdx, index.mdx, and overview.mdx
Security is available
Documentation content improvements
classifications, refined deployment options, updated
permit.check() parameters, added user_profile resource for
relationship-based permission derivation
now select from pre-approved permissions rather than free-form
grants; improved step-by-step setup guidance; added direct links
to Dashboard, MCP Servers, and Humans pages
description to match new terminology
intro
Mermaid diagram rendering fixes
labels (fill, opacity) to prevent label/arrow overlap in
flowcharts and sequence diagrams
better background color handling and edge label visibility
Housekeeping
refresh)
Issues resolved
PER-13548
PER-14101
PER-14102
PER-14124
PER-14125
PER-14103
per-14106
PER-14107
PER-14104
PER-14105