Refactor MCP Permissions documentation to Agent Security terminology#610
Refactor MCP Permissions documentation to Agent Security terminology#610
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. |
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.
| | **Hosting Platform** | Building a multi-tenant MCP SaaS | MCPermit baked into ingress; tenants consume via hosted endpoints | | ||
| | Pattern | When to Use | How It Works | Status | | ||
| | ------------------------- | -------------------------------- | ----------------------------------------------------------------- | ------ | | ||
| | **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security` | Available | |
There was a problem hiding this comment.
The hosted gateway URL shown here omits the /mcp path, but elsewhere (e.g., the Getting Started guide) the MCP endpoint is https://<host>.agent.security/mcp. This mismatch is likely to cause misconfiguration; update the URL in this table (or clarify base vs MCP endpoint) to be consistent.
| | **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security` | Available | | |
| | **Hosted Gateway** | Fastest rollout; SaaS workloads | Point agents/servers to `https://<host>.agent.security/mcp` | Available | |
| description: A comprehensive guide to implementing and managing permissions for Model Context Protocol (MCP) servers | ||
| sidebar_position: 3 | ||
| description: Set up and manage Agent Security to audit and enforce permissions on MCP server access for your organization. | ||
| sidebar_position: 1 |
There was a problem hiding this comment.
This sets the guide to sidebar_position: 1, which conflicts with the Overview page also being position 1 in this section. To avoid ambiguous/unstable ordering in the sidebar, assign a unique position (e.g., keep Overview=1, Architecture=2, Getting Started=3).
| sidebar_position: 1 | |
| sidebar_position: 3 |
| ### Policy Architecture | ||
|
|
||
| MCPermit automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on: | ||
| Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on: |
There was a problem hiding this comment.
Hyphenate the compound modifier: change 'Relationship based' to 'Relationship-based' for correct grammar.
| Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship based Access Control) policies based on: | |
| Agent Security automatically generates Google-Zanzibar-inspired ReBAC (Relationship-based Access Control) policies based on: |
| - 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, you'll need to enter OAuth credentials (Client ID / Secret) manually | ||
| 3. Review the discovered tools: | ||
| - Each tool is auto-classified with a trust level based on its name (see [trust level reference](#trust-level-reference)) |
There was a problem hiding this comment.
Grammar: 'Each tool ... based on its name' is awkward in context (tools plural overall). Consider changing 'its name' to 'its name pattern' or (if referring to tools collectively) 'their names'.
| - Each tool is auto-classified with a trust level based on its name (see [trust level reference](#trust-level-reference)) | |
| - Each tool is auto-classified with a trust level based on its name pattern (see [trust level reference](#trust-level-reference)) |
| # Getting Started with Agent Security | ||
|
|
||
| MCPermit provides a secure permissions layer for Model Context Protocol (MCP) servers, enabling fine-grained access control, authentication, and audit capabilities for AI agents. | ||
| Agent Security Gateway is a managed proxy between MCP clients (Cursor, Claude Desktop, VS Code, and others) and upstream MCP servers. |
There was a problem hiding this comment.
This sentence reads like it’s missing an article; consider 'The Agent Security Gateway is ...' for smoother, more standard phrasing (and to match the more formal tone used elsewhere in the docs).
| Agent Security Gateway is a managed proxy between MCP clients (Cursor, Claude Desktop, VS Code, and others) and upstream MCP servers. | |
| The Agent Security Gateway is a managed proxy between MCP clients (Cursor, Claude Desktop, VS Code, and others) and upstream MCP servers. |
|
The latest updates on your projects. Learn more about Argos notifications ↗︎
|
1 participant
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.