Skip to main content

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.

info

This pages describes an upcoming product; details are subject to change. To get early access to MCPermit, contact us via email or via Slack.

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

TermMeaning in MCPermit
OriginatorHuman user delegating authority to an agent
AgentMCP client acting on behalf of an originator
MCP ServerTool endpoint that implements the MCP spec (e.g., Gmail-MCP)
GatewayMCPermit proxy enforcing policy at mcp.permit.io
PDPEmbedded policy engine (OPA + OPAL)
Project / EnvironmentConfig scope in the UI (e.g., My-App / Prod)
On-Behalf-OfRelationship linking originator ↔ agent ↔ server

How it works

  1. Gateway routing: All MCP traffic flows through the gateway
  2. Policy enforcement: The PDP evaluates each request against defined policies
  3. Audit logging: All actions are logged for compliance and monitoring
  4. Human oversight: Optional approval workflows for sensitive operations

Setting up MCPermit

Initial gateway setup

  1. Create an organization

    • Sign in via company SSO
    • Create new organization
  2. Configure deployment

    • Choose between hosted or self-hosted
    • Set up in Settings ▸ Gateway
  3. Connect identity

    • Configure OIDC/SAML
    • Map groups to roles in Settings ▸ Identity
  4. Define policies

    • Configure allowed agent-type ↔ server-type pairs
    • Set up in Policy Builder
  5. 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

  1. Add MCP server

    • Navigate to Dashboard ▸ MCP Servers ▸ ➕ Register
    • Select server type (personal, corporate, sensitive)
    • Configure gateway URL
    • Update reverse-proxy or server config
  2. 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

SymptomLikely CauseFix
403 – identify_self requiredAgent skipped identify_selfEnsure SDK auto-invokes or call manually
No agents visibleDelegation incompleteResend approval link in Agents ▸ Pending
TimeoutsSelf-hosted gateway cannot reach the PDPCheck OPAL side-car or switch to embedded PDP
Missing logsLog sink offlineSettings ▸ 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?

info

This pages describes an upcoming product; details are subject to change. To get early access to MCPermit, contact us via email or via Slack.

Secure your AI in minutes - route it through mcp.permit.io and relax.