MCPermit - User's Guide
Version 0.1.2
Introduction
MCPermit adds a drop-in permissions layer to any Model Context Protocol (MCP) server.
Routing traffic through the gateway at https://mcp.permit.io
Using MCPermit ensures every AI-agent call is:
- Authenticated – ties together user & agent identities.
- Authorized – enforced with fine-grained ReBAC.
- Audited – full log plus anomaly alerts.
- Optionally approved – human-in-the-loop (HITL) for risky operations.
All surfaced through one console.
Core Concepts
| Term | Meaning in MCPermit |
|---|---|
| Originator | Human user delegating authority to an agent. |
| Agent | MCP client acting on behalf of an originator. |
| MCP Server | Tool endpoint that implements the MCP spec (e.g., Gmail-MCP). |
| Gateway | MCPermit proxy enforcing policy at mcp.permit.io. |
| PDP | Embedded Permit.io policy engine (OPA + OPAL). |
| Project / Environment | Config scope in the UI (e.g., My-App / Prod). |
| On-Behalf-Of | Relationship linking originator ↔ agent ↔ server. |
Persona-Based Quick Starts
3.1 Application Security - Initial Gateway Setup
| Step | Action | Where |
|---|---|---|
| 1 | Create an Org – Sign in via company SSO → Create new org. | Web console |
| 2 | Select Deployment – Hosted (default) or Self-hosted. | Settings ▸ Gateway |
| 3 | Connect SSO – OIDC/SAML wizard → map groups to roles. | Settings ▸ Identity |
| 4 | Define Org Policy – choose allowed agent-type ↔ server-type pairs (e.g., chat → personal). | Policy Builder |
| 5 | Invite Dev Team – assign the Developer role. | Directory ▸ Originators |
| 6 | Verify Logs – run the sample agent and confirm traffic under Audit ▸ Logs. | Main pane |
Hosted URL pattern
[https://mcp.permit.io/](https://mcp.permit.io/)<org>/<env>/<service>
(Self-hosted keeps the same path structure behind your own domain.)
3.2 Developers - Registering Servers and Agents
-
Add Your MCP Server
Dashboard ▸ MCP Servers ▸ ➕ Register- Choose Server Type (
personal,corporate,sensitive, …). - Copy the Gateway URL (example:
https://mcp.permit.io/acme/prod/gmail-mcp). - Point your reverse-proxy or server config to that path.
- Choose Server Type (
-
Instrument the Agent
# Minimal change – point to the gateway
export MCP_BASE_URL=https://mcp.permit.io/acme/prod
python run_my_agent.py
The gateway will redirect to identify_self if delegation is missing.
-
Scopes & Functions MCP Servers ▸ server ▸ Functions
- Toggle Requires identify_self (default ON).
- Tag functions with clear labels (
Read Email,Create Event).
-
Local Testing Use Preview to replay calls and view JWT claims, Rego decision traces, and audit entries.
3.3 End-Users - Authorizing and Monitoring Agents
| What You Do | How |
|---|---|
| Run the agent (first time) | Agent shows an approval dialog hosted at mcp.permit.io. |
| Grant or deny scopes | For each MCP server, click Allow or Cancel. |
| View activity | Detect ▸ Logs → filter by My Agents. |
| Step-Up approval | Slack/email prompt for sensitive ops → click to approve or block. |
| Revoke access | Directory ▸ Agents → Revoke Delegation (calls blocked immediately). |
Example Authorize Agent UI Flow
Note: Clicking Authorize Agent will authorize the agent to access the MCP server, and will redirect to the external tools' OAuth flow, and then back to the agent's configured callback URL.
Navigation & UI Reference
| Sidebar Section | What You'll Find |
|---|---|
| Directory | Originators, Agents, MCP Servers. |
| Audit | Logs (search), Anomaly (risk scoring), Chains of Trust (graph). |
| Detect | DLP findings, SCAN (scope drift). |
Top-left Project / Environment selector scopes every view.
Global Policy Management Cheat-Sheet
| Goal | UI Path | Example |
|---|---|---|
| Block all ambient agents from sensitive servers | Policy Builder ▸ Org Rules | deny { agent_type == "ambient"; server_type == "sensitive" } |
Allow Alice's bot to create_event only 09-18 local | Agent Rules + time condition | allow { originator == "alice"; func == "create_event"; hour < 18 } |
| Require HITL for deletes | In the function row, toggle Requires Approval | delete_message |
Visual edits compile to Rego and hot-push to every gateway.
Troubleshooting
| Symptom | Likely Cause | Fix |
|---|---|---|
| 403 – identify_self required | Agent skipped identify_self. | Ensure SDK auto-invokes or call manually. |
| No agents visible | Delegation incomplete. | Resend approval link in Agents ▸ Pending. |
| Timeouts | Self-hosted gateway cannot reach the PDP. | Check OPAL side-car or switch to embedded PDP. |
| Missing logs | Log sink offline. | Settings ▸ Logging → test sink or use local store. |
Glossary
| Term | Definition |
|---|---|
| Agent Type | Behaviour class (chat, proactive, ambient). |
| Server Type | Risk tag (personal, financial, sensitive). |
| HITL | Human-in-the-loop approval. |
| ReBAC | Relationship-based access control. |
| OPA / OPAL | Open Policy Agent / policy push layer. |
Need help?
Support: support@permit.io
Slack: Slack #agentic-ai
Secure your AI in minutes — route it through mcp.permit.io and relax.