Getting Started with Agent Security

Agent Security Gateway is a managed proxy between MCP clients (Cursor, Claude Desktop, VS Code, and others) and upstream MCP servers. It authenticates users, enforces per-tool permissions through trust levels, and logs every tool call for audit.

Prerequisites

A Permit.io account
An organization-scoped API key from Permit.io Settings > API Keys (used to connect your organization)
A project/environment-scoped API key for each host you create (used to link the host to a Permit environment)

Go to app.agent.security
Create an account
Connect your Permit.io organization:
- Go to Permit.io Settings > API Keys
- Create an organization-scoped API key
- Paste the key into the Agent Security platform

Once connected, your organization name appears in the sidebar. You can connect multiple organizations and switch between them from the sidebar menu.

2. Create a host

A host is a gateway instance with its own subdomain, policies, users, and sessions. Each host maps to a Permit.io environment.

Go to Hosts and click Create Host
Fill in:
- Subdomain prefix — e.g., acme (a unique suffix like pink-panda-6942 is auto-generated)
- Permit API Key — a project/environment-scoped key that determines which Permit environment this host uses
Click Create Host

Your gateway is now live at:

https://acme-pink-panda-6942.agent.security/mcp

The host detail page shows the full MCP URL and ready-to-copy configuration snippets for MCP clients.

3. Import MCP servers

The import wizard connects to an upstream MCP server, discovers its tools, and creates the corresponding resources and permissions in Permit.

Go to MCP Servers and click Create Server
Enter the upstream MCP server URL (e.g., https://mcp.linear.app/mcp) and click Connect
- 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
Review the discovered tools:
- Each tool is auto-classified with a trust level based on its name (see trust level reference)
- You can override the trust level per tool and enable or disable individual tools
Click Import

Edit an MCP server

After import, manage the server from its detail page in app.agent.security:

Add or remove tools
Change trust levels per tool
Update the server name and description
Remove the server entirely

4. Manage agents and permissions

Agents

Agents are MCP clients that connect through the gateway. They appear automatically on the Agents page after a user completes the consent flow.

For each agent you can:

View which MCP servers it has access to and at what trust level
Change its trust level per server
Revoke access to specific servers

Humans

Humans are users who signed in through the consent flow and authorized MCP clients. They appear on the Humans page automatically — no manual creation is needed.

Give your users the gateway MCP URL so they can connect their MCP clients. The host detail page in app.agent.security provides ready-to-copy configuration snippets for each client.

Cursor / VS Code

Add to .cursor/mcp.json (Cursor) or your VS Code MCP settings:

{
  "mcpServers": {
    "agent-security": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"]
    }
  }
}

Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agent-security": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://acme-pink-panda-6942.agent.security/mcp"]
    }
  }
}

Claude Code

claude mcp add agent-security --transport http https://acme-pink-panda-6942.agent.security/mcp

Pre-configured upstream URL

To link users directly to a specific MCP server, append the upstream URL as a query parameter:

https://acme-pink-panda-6942.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp

The consent UI will have the upstream server pre-filled so users don't need to enter it manually. This is useful when you want to share a direct link to a specific MCP server.

When a user connects an MCP client for the first time, they complete a one-time consent flow:

Sign in — the MCP client opens a browser window where the user creates an account or logs in
Enter upstream MCP server URL — the user types the URL of the MCP server they want to access (or it's pre-filled via a pre-configured upstream URL)
Authenticate with the upstream server — if the MCP server requires OAuth, the user is redirected to sign in with the upstream provider (e.g., GitHub, Linear)
Review tools and set trust level — the consent screen shows all discovered tools with a trust level selector. Tools are marked as allowed or denied in real time as the user adjusts the trust level.
Accept — permissions are synced to Permit and the MCP client receives an access token

On subsequent connections the existing session is reused until it expires or is revoked.

7. Runtime authorization

Every tool call from an MCP client is authorized in real time:

The MCP client sends a call_tool request with a Bearer token
The gateway verifies the token and identifies the agent
The gateway checks Permit: "Can this agent call this tool on this MCP server?"
Allowed — the call is proxied to the upstream MCP server
Denied — the client receives a permission denied error

Authorization is based on the trust level assigned during consent. For example, an agent with medium trust can call low and medium trust tools, but not high trust tools.

8. Audit logs

Every authorization decision — allowed or denied — is recorded in Permit audit logs with:

Which agent (MCP client) made the request
Which tool was called
Which MCP server was targeted
Whether the request was allowed or denied

View audit logs in the Permit.io dashboard under your environment's Audit Log section.

Trust level reference

Tools are auto-classified into trust levels based on naming patterns during import. You can override the level for any tool.

Trust level	Includes	Naming patterns	Examples
Low	Read-only operations	`get_`, `list_`, `read_`, `search_`, `find_*`	`get_user`, `list_issues`, `search_files`
Medium	Low + write operations	`create_`, `update_`, `set_`, `send_`, `execute_`, `run_`	`create_issue`, `update_record`, `send_message`
High	Low + medium + destructive operations	`delete_`, `remove_`, `destroy_`, `drop_`, `purge_*`	`delete_repo`, `remove_member`, `destroy_environment`

Trust levels are hierarchical: high includes all medium and low permissions, medium includes all low permissions.

Tools that don't match any pattern default to low trust.

Troubleshooting

Symptom	Likely cause	Fix
MCP client shows "host not found"	Gateway URL is incorrect or host doesn't exist	Verify the URL on the Hosts page in app.agent.security
"Permission denied" on a tool call	Agent's trust level is too low for that tool	Change the agent's trust level on the Agents page
OAuth redirect fails during consent	Upstream MCP server requires manual OAuth credentials	Re-import the server and provide Client ID / Secret when prompted
Tools not appearing after import	Tools may be disabled	Check the server detail page and enable the missing tools
User can't complete consent flow	Browser blocks pop-ups from the MCP client	Allow pop-ups for the `agent.security` domain
Token expired errors	Session has expired	The user needs to reconnect — the consent flow will run again

Prerequisites​

1. Sign up and connect your organization​

2. Create a host​

3. Import MCP servers​

Edit an MCP server​

4. Manage agents and permissions​

Agents​

Humans​

5. Share with your users​

Cursor / VS Code​

Claude Desktop​

Claude Code​

Pre-configured upstream URL​

6. User consent flow​

7. Runtime authorization​

8. Audit logs​

Trust level reference​

Troubleshooting​

Contents