Quick start

This guide sets up one upstream MCP server, one policy, one grant, and one MCP client routed through the PolicyLayer proxy.

You need an admin role to complete the full setup. policy_manager users can handle policy work, but not server setup or token management; see Roles.

On first sign-in, create an organisation. You join it as admin. You can invite teammates from the organisation page later.

2. Register an upstream server

In the sidebar, open MCP Servers, then click Add server.

Enter:

Upstream URL: search the popular-server list or paste your own HTTP MCP server URL.
Name: a short label, such as prod-stripe, github, or linear.

When you choose a popular server, PolicyLayer fills in the URL and a name. You can edit either before submitting.

After creation, PolicyLayer opens the server detail page. The page shows the upstream URL, the PolicyLayer proxy URL, and a Quick start strip for finishing setup.

3. Configure upstream authentication

If the upstream requires OAuth, use the OAuth section to connect it.

If the upstream expects fixed headers, use Static headers. Common examples are API keys, tenant IDs, or API-version headers.

If the upstream does not require authentication, you can skip this step.

Agents do not receive upstream credentials. They authenticate to PolicyLayer with a grant token; PolicyLayer sends the configured upstream credentials when forwarding allowed requests.

4. Create a policy

On the server detail page, open Policies, then click New policy.

The policy editor loads the upstream tool list, so you can decide what each tool should do:

Allow: the tool can be called.
Deny: the tool is visible but blocked.
Hide: the tool is removed from tools/list and blocked.
Custom: add argument rules and limits, such as “deny refunds over $100” or “limit this grant to 30 calls per minute.”

Use the visual builder for normal policy work, or switch to Raw JSON when you want direct control. For the full policy format, see Writing policies.

Save the policy.

5. Mint a grant

Open Grants, then click New grant.

A grant is a labelled bearer token for one MCP client or automation. Use labels like:

alice-laptop
ci-runner
support-agent

Choose the policy that should gate the grant. A grant with no policy denies every call until you attach one.

After minting, use SETUP or REVEAL on the grant row to show the token and client configuration. Admins can rotate or revoke the grant later without affecting other grants on the same server.

6. Connect your MCP client

The server detail page shows the PolicyLayer proxy URL:

https://proxy.policylayer.com/mcp/<server-uuid>/

Configure your MCP client to connect to that URL with:

Authorization: Bearer <grant-token>

The exact config format depends on the client. Use the SETUP button on the grant row for a copy-paste snippet, or see Integrations for client-specific examples.

7. Check proxy logs

After the client makes calls, open the server’s Proxy Logs tab.

Each row shows the grant, tool, policy decision, outcome, status, timestamp, and argument keys. Argument values are not stored.