MCPermit - User's Guide
MCPermit provides a secure permissions layer for Model Context Protocol (MCP) servers, enabling fine-grained access control, authentication, and audit capabilities for AI agents.
What is MCPermit?
MCPermit adds a permissions layer to any Model Context Protocol (MCP) server by routing traffic through the gateway at https://mcp.permit.io
. This 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 these capabilities are managed through a single console interface.
Core concepts
Key components
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 policy engine (OPA + OPAL) |
Project / Environment | Config scope in the UI (e.g., My-App / Prod) |
On-Behalf-Of | Relationship linking originator ↔ agent ↔ server |
How it works
- Gateway routing: All MCP traffic flows through the gateway
- Policy enforcement: The PDP evaluates each request against defined policies
- Audit logging: All actions are logged for compliance and monitoring
- Human oversight: Optional approval workflows for sensitive operations
Setting up MCPermit
Initial gateway setup
-
Create an organization
- Sign in via company SSO
- Create new organization
-
Configure deployment
- Choose between hosted or self-hosted
- Set up in Settings ▸ Gateway
-
Connect identity
- Configure OIDC/SAML
- Map groups to roles in Settings ▸ Identity
-
Define policies
- Configure allowed agent-type ↔ server-type pairs
- Set up in Policy Builder
-
Team setup
- Invite development team
- Assign appropriate roles
URL structure
Hosted URL pattern:
https://mcp.permit.io/<org>/<env>/<service>
Self-hosted deployments maintain the same path structure behind your domain.
Managing permissions
Server registration
-
Add MCP server
- Navigate to Dashboard ▸ MCP Servers ▸ ➕ Register
- Select server type (
personal
,corporate
,sensitive
) - Configure gateway URL
- Update reverse-proxy or server config
-
Agent configuration
export MCP_BASE_URL=https://mcp.permit.io/acme/prod
python run_my_agent.py
Function configuration
In MCP Servers ▸ server ▸ Functions:
- Toggle Requires identify_self (default ON)
- Tag functions with descriptive labels
- Configure approval requirements
Monitoring and auditing
Activity monitoring
- View agent activity in Detect ▸ Logs
- Filter by specific agents or time periods
- Monitor for anomalies and security events
Access management
- Review and manage agent delegations
- Configure step-up approvals for sensitive operations
- Revoke access when needed
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 |
Conclusion
MCPermit provides a comprehensive permissions layer for MCP servers, enabling secure and auditable AI agent operations. By routing traffic through the gateway and enforcing fine-grained policies, organizations can maintain control over their AI operations while enabling innovation.
Need help?
- Support: support@permit.io
- Slack: Slack
#agentic-ai
Secure your AI in minutes - route it through mcp.permit.io and relax.