diff --git a/docs/permit-mcp-gateway/demos/_category_.json b/docs/permit-mcp-gateway/demos/_category_.json new file mode 100644 index 000000000..ce25b6002 --- /dev/null +++ b/docs/permit-mcp-gateway/demos/_category_.json @@ -0,0 +1,12 @@ +{ + "label": "Usage Examples and Demos", + "position": 10, + "collapsible": true, + "collapsed": true, + "link": { + "type": "generated-index", + "slug": "/permit-mcp-gateway/demos", + "title": "Usage Examples and Demos", + "description": "Step-by-step demos showing how to use Permit MCP Gateway to enforce trust-based access control on real MCP servers." + } +} diff --git a/docs/permit-mcp-gateway/demos/linear-mcp-gateway.mdx b/docs/permit-mcp-gateway/demos/linear-mcp-gateway.mdx new file mode 100644 index 000000000..429e5af20 --- /dev/null +++ b/docs/permit-mcp-gateway/demos/linear-mcp-gateway.mdx @@ -0,0 +1,126 @@ +--- +sidebar_position: 1 +title: "Linear MCP Gateway Demo" +description: "Enforce trust-based access control on Linear's MCP server — allow a Developer to create issues while restricting a Project Manager to read-only access." +--- + +# Linear MCP Gateway Demo + +A walkthrough demonstrating how to set up Permit.io's Agent Security MCP Gateway so that users with different trust levels are limited in what they can do with their Linear MCP tools. + +## Problem Statement + +When exposing Linear's MCP server to multiple users or AI agents, everyone gets the same level of access by default. An intern and a team lead can both create issues, delete comments, and modify projects — there's no way to enforce least-privilege access out of the box. + +This demo shows how to solve that by placing Permit.io's MCP Gateway in front of the Linear MCP server. + +**Task:** Use Permit.io's MCP Gateway to allow a Developer (High trust) to create Linear issues and a Project Manager (Medium trust) to only list Linear issues. + +## Before You Begin + +1. [Create a Permit.io Account](/quickstart/#1-create-a-permit-account) +2. [Create an Agent Security Account](/permit-mcp-gateway/guide) + +## Step 1 — Set Up Your Host and MCP + +1. Go to the [**Dashboard**](https://app.agent.security/) and select **Hosts**, then click **Create Host**. + + ![Create Host button in the Dashboard](/img/mcpermit/linear-demo/create-host.png) + +2. Fill in: + - **Subdomain** — choose a prefix (e.g., `my-tenant`). A unique suffix is auto-generated. + - **Project** — select the Permit project that contains the environment you want to use. + - **Environment** — select the Permit environment this host will use. The environment cannot be changed after the host is created. + + ![Host creation form with subdomain, project, and environment fields](/img/mcpermit/linear-demo/host-details.png) + +3. Click **Create Host**. + +4. The Host you created exists but has no abilities because it is not linked to an external MCP. Click **MCP Servers** to create an MCP server. + + ![MCP Servers tab in host configuration](/img/mcpermit/linear-demo/mcp-servers.png) + +5. Enter the Linear MCP URL: `https://mcp.linear.app/mcp`. Upon pressing **Connect**, you will be prompted by Linear to sign in. + + ![Entering the Linear MCP URL](/img/mcpermit/linear-demo/linear-mcp-url.png) + +6. All of the tools available to the Linear MCP are shown as imported. For this demo we only need two tools: `list_issues` and `save_issue`. Set `save_issue` to **High** trust and `list_issues` to **Medium** trust. You can adjust tool trust levels afterwards as well. + + ![Tool trust level configuration showing list_issues and save_issue](/img/mcpermit/linear-demo/tool-trust-levels.png) + +Your MCP Gateway now has Linear MCP abilities. + +## Step 2 — Add Users + +To add users in your organization, they will need the Gateway MCP URL found in the **Dashboard** tab. + +![Dashboard showing the Gateway MCP URL](/img/mcpermit/linear-demo/dashboard-mcp-url.png) + +### Developer Signs Up with Claude Desktop + +The Developer can add the MCP configuration object found in the Dashboard into the Claude Desktop config file, or add the MCP URL via the Claude Desktop UI. + +Upon adding the MCP connector and connecting, the Developer will be brought to the MCP Gateway Consent Service to sign in or register an account. + +![Consent Service sign-in page](/img/mcpermit/linear-demo/consent-signin.png) + +![Consent Service registration page](/img/mcpermit/linear-demo/consent-signup.png) + +Upon signing in, the new user will not have any MCPs available because the admin has not yet granted access. + +![Empty MCP list for new user](/img/mcpermit/linear-demo/no-mcps.png) + +Navigate to **Humans** in the Dashboard — you will see the new user has registered. Grant the user MCP Server Access to the Linear MCP created previously. Because this user is a Developer, set the **Max Trust Level** to **High**. + +![Granting High trust level access to the Developer](/img/mcpermit/linear-demo/grant-access-high.png) + +After refreshing, the user will see the MCP available for selection. Upon selecting it, they must authorize via Linear. + +![MCP available for selection in the Consent Service](/img/mcpermit/linear-demo/mcp-available.png) + +![Linear OAuth authorization prompt](/img/mcpermit/linear-demo/linear-auth.png) + +![Successfully connected confirmation](/img/mcpermit/linear-demo/connected.png) + +The user can also set restrictions on their agent's use of the MCP. See the [Consent Service](/permit-mcp-gateway/consent-service) documentation to learn more. + +![User consent restrictions interface](/img/mcpermit/linear-demo/consent-restrictions.png) + +### Project Manager Signs Up with Claude Code + +The signup and consent service procedure is the same as described above. The only difference is that when the admin assigns access, the **Max Trust Level** is set to **Medium** instead of High. + +This is what the Project Manager will see when connecting Claude Code to the MCP: + +![Project Manager connected with Medium trust level](/img/mcpermit/linear-demo/pm-medium-trust.png) + +## Step 3 — Test Actions by User + +### PM (Claude Code) Tries to Create Issue + +![PM receives Permission Denied when trying to save_issue](/img/mcpermit/linear-demo/pm-create-denied.png) + +As expected, the PM does not have a high enough trust level and is returned **Permission Denied** for `save_issue`. + +### Developer (Claude Desktop) Tries to Create Issue + +![Developer successfully creates an issue](/img/mcpermit/linear-demo/dev-create-success.png) + +As expected, the Developer successfully creates an issue. + +### Both Users List Issues + +![PM successfully lists issues](/img/mcpermit/linear-demo/pm-list-issues.png) + +![Developer successfully lists issues](/img/mcpermit/linear-demo/dev-list-issues.png) + +As expected, both the Project Manager and Developer succeed in listing issues — their trust levels meet the Medium trust requirement of the `list_issues` tool. + +## Summary + +| User | Trust Level | `list_issues` (Medium) | `save_issue` (High) | +|------|-------------|----------------------|---------------------| +| Developer | High | Allowed | Allowed | +| Project Manager | Medium | Allowed | Denied | + +This demo shows how Permit MCP Gateway enforces least-privilege access on MCP tools based on trust levels — without any changes to the underlying Linear MCP server. diff --git a/docs/permit-mcp-gateway/demos/n8n-linear-mcp-gateway.mdx b/docs/permit-mcp-gateway/demos/n8n-linear-mcp-gateway.mdx new file mode 100644 index 000000000..e2232b9ea --- /dev/null +++ b/docs/permit-mcp-gateway/demos/n8n-linear-mcp-gateway.mdx @@ -0,0 +1,102 @@ +--- +sidebar_position: 2 +title: "n8n Workflow with Linear MCP Gateway" +description: "Use Permit.io's MCP Gateway to control which Linear MCP tools an n8n workflow can access — and revoke access in real time." +--- + +# n8n Workflow with Linear MCP Gateway + +A walkthrough demonstrating how to set up Permit.io's Agent Security MCP Gateway so that you can trust automated workflows built with n8n. + +## Problem Statement + +Automated workflow builders like n8n allow you to connect to external MCPs — automated tools calling automated tools. But who is monitoring all of this? Where are the checks on the system? + +That is where Permit.io's MCP Gateway comes in. Using the MCP Gateway, you can control exactly which tools an agent or workflow can use. + +This demo shows how to solve that by placing Permit.io's MCP Gateway in front of a n8n workflow. + +**Task:** Use Permit.io's MCP Gateway to allow an n8n workflow to access only specific tools of a Linear MCP. + +## Before You Begin + +1. [Create a Permit.io Account](/quickstart/#1-create-a-permit-account) +2. [Create an Agent Security Account](/permit-mcp-gateway/guide) +3. [Add Linear MCP to your Account](/permit-mcp-gateway/demos/linear-mcp-gateway) + +## The n8n Workflow + +For this demo, assume you use two popular tools for work management: **Attio** (CRM) and **Linear** (project tracking). You have an Attio object that tracks all customers. For every new sale, you want to automatically create a Linear issue. Let's automate this with an n8n workflow. + +The workflow has three components: + +1. **API Webhook Listener (Attio)** — listens for new items added to Attio +2. **HTTP Fetcher** — retrieves the new item data from Attio +3. **MCP Client** — calls the MCP Gateway to create a Linear issue with the item data + +![n8n workflow overview showing webhook, fetcher, and MCP client nodes](/img/mcpermit/n8n-linear-demo/workflow-overview.png) + +Since this demo focuses on the MCP Gateway integration, we'll skip to component 3 — the MCP Client. + +## Step 1 — Configure the MCP Client in n8n + +1. In your n8n workflow, grab **MCP Client** from the tool selector on the right. + + ![MCP Client in the n8n tool selector](/img/mcpermit/n8n-linear-demo/mcp-client-tool-selector.png) + +2. Insert the URL from the Linear MCP you created previously in the Agent Security Platform. For **Authentication**, select **MCP OAuth2** and then **Create New Credential**. + + ![MCP Client configuration with URL and authentication](/img/mcpermit/n8n-linear-demo/mcp-client-config.png) + +3. In the **Create New Credential** modal, enter the MCP Endpoint URL again and press **Connect to MCP**. + + ![Create New Credential modal with MCP endpoint URL](/img/mcpermit/n8n-linear-demo/create-credential.png) + +4. This brings you to the Consent Service screen to select which MCP to include for this workflow. Select the **Linear MCP**. + + ![Consent Service screen showing Linear MCP selection](/img/mcpermit/n8n-linear-demo/consent-service-select.png) + +5. You will be prompted to sign in and grant access to Linear. Then you will be asked to import and assign trust levels for all of Linear's tools. This is where you directly control what n8n can do. + + ![Tool import screen with trust level assignment](/img/mcpermit/n8n-linear-demo/tool-import.png) + +## Step 2 — Configure the Linear Action + +1. In the MCP Client config area, n8n now shows all the imported Linear tools. Select **save_issue**. + + ![Selecting save_issue from imported Linear tools](/img/mcpermit/n8n-linear-demo/select-save-issue.png) + +2. Define the **team** for the issue. Then pass along whatever data you need — for this demo, we use the customer name and sale amount for the Linear issue title and description. + + ![Configuring issue fields with customer data](/img/mcpermit/n8n-linear-demo/issue-config.png) + +## Step 3 — Test the Workflow + +As long as the trust level is set appropriately for this user/agent, every time a new item is added to the Attio object, a Linear issue will be created automatically. + +![Completed n8n workflow execution](/img/mcpermit/n8n-linear-demo/workflow-complete.png) + +![Linear issue created from Attio data](/img/mcpermit/n8n-linear-demo/linear-issue-created.png) + +![Attio item that triggered the workflow](/img/mcpermit/n8n-linear-demo/attio-item.png) + +## Step 4 — Adjust Trust Levels in Real Time + +If at any time you want to change what n8n can do with the Linear MCP, go to the Agent Security dashboard and toggle the trust level. + +![Agent Security dashboard showing trust level controls](/img/mcpermit/n8n-linear-demo/trust-level-dashboard.png) + +![Setting trust level to Low for the workflow](/img/mcpermit/n8n-linear-demo/trust-level-low.png) + +For example, setting the trust level to **Low** causes the Linear MCP to fail execution — the MCP Gateway blocks the action. + +![n8n execution log showing blocked MCP action](/img/mcpermit/n8n-linear-demo/execution-blocked.png) + +## Summary + +This demo shows how Permit.io's MCP Gateway gives you real-time control over what automated n8n workflows can do with external MCPs like Linear — without any changes to the underlying MCP server or n8n workflow logic. + +| Trust Level | `save_issue` Result | +|-------------|-------------------| +| High | Allowed — issue created | +| Low | Blocked — MCP Gateway denies the action | diff --git a/sidebars.js b/sidebars.js index 7961b4c4a..c6d04ec4e 100644 --- a/sidebars.js +++ b/sidebars.js @@ -214,6 +214,23 @@ const sidebars = { "permit-mcp-gateway/architecture", "permit-mcp-gateway/permit-integration", "permit-mcp-gateway/advanced-features", + { + type: "category", + label: "Usage Examples and Demos", + link: { + type: "generated-index", + slug: "/permit-mcp-gateway/demos", + title: "Usage Examples and Demos", + description: + "Step-by-step demos showing how to use Permit MCP Gateway to enforce trust-based access control on real MCP servers.", + }, + items: [ + { + type: "autogenerated", + dirName: "permit-mcp-gateway/demos", + }, + ], + }, ], }, ], diff --git a/static/img/mcpermit/linear-demo/connected.png b/static/img/mcpermit/linear-demo/connected.png new file mode 100644 index 000000000..33473ff28 Binary files /dev/null and b/static/img/mcpermit/linear-demo/connected.png differ diff --git a/static/img/mcpermit/linear-demo/consent-restrictions.png b/static/img/mcpermit/linear-demo/consent-restrictions.png new file mode 100644 index 000000000..4ed61b7f9 Binary files /dev/null and b/static/img/mcpermit/linear-demo/consent-restrictions.png differ diff --git a/static/img/mcpermit/linear-demo/consent-signin.png b/static/img/mcpermit/linear-demo/consent-signin.png new file mode 100644 index 000000000..85864d6fe Binary files /dev/null and b/static/img/mcpermit/linear-demo/consent-signin.png differ diff --git a/static/img/mcpermit/linear-demo/consent-signup.png b/static/img/mcpermit/linear-demo/consent-signup.png new file mode 100644 index 000000000..e1ece7ade Binary files /dev/null and b/static/img/mcpermit/linear-demo/consent-signup.png differ diff --git a/static/img/mcpermit/linear-demo/create-host.png b/static/img/mcpermit/linear-demo/create-host.png new file mode 100644 index 000000000..5a7c48783 Binary files /dev/null and b/static/img/mcpermit/linear-demo/create-host.png differ diff --git a/static/img/mcpermit/linear-demo/dashboard-mcp-url.png b/static/img/mcpermit/linear-demo/dashboard-mcp-url.png new file mode 100644 index 000000000..750aa14af Binary files /dev/null and b/static/img/mcpermit/linear-demo/dashboard-mcp-url.png differ diff --git a/static/img/mcpermit/linear-demo/dev-create-success.png b/static/img/mcpermit/linear-demo/dev-create-success.png new file mode 100644 index 000000000..f917d64ae Binary files /dev/null and b/static/img/mcpermit/linear-demo/dev-create-success.png differ diff --git a/static/img/mcpermit/linear-demo/dev-list-issues.png b/static/img/mcpermit/linear-demo/dev-list-issues.png new file mode 100644 index 000000000..832297162 Binary files /dev/null and b/static/img/mcpermit/linear-demo/dev-list-issues.png differ diff --git a/static/img/mcpermit/linear-demo/grant-access-high.png b/static/img/mcpermit/linear-demo/grant-access-high.png new file mode 100644 index 000000000..703007157 Binary files /dev/null and b/static/img/mcpermit/linear-demo/grant-access-high.png differ diff --git a/static/img/mcpermit/linear-demo/host-details.png b/static/img/mcpermit/linear-demo/host-details.png new file mode 100644 index 000000000..be349088c Binary files /dev/null and b/static/img/mcpermit/linear-demo/host-details.png differ diff --git a/static/img/mcpermit/linear-demo/linear-auth.png b/static/img/mcpermit/linear-demo/linear-auth.png new file mode 100644 index 000000000..2fd523562 Binary files /dev/null and b/static/img/mcpermit/linear-demo/linear-auth.png differ diff --git a/static/img/mcpermit/linear-demo/linear-mcp-url.png b/static/img/mcpermit/linear-demo/linear-mcp-url.png new file mode 100644 index 000000000..2fd523562 Binary files /dev/null and b/static/img/mcpermit/linear-demo/linear-mcp-url.png differ diff --git a/static/img/mcpermit/linear-demo/mcp-available.png b/static/img/mcpermit/linear-demo/mcp-available.png new file mode 100644 index 000000000..df71a8a4a Binary files /dev/null and b/static/img/mcpermit/linear-demo/mcp-available.png differ diff --git a/static/img/mcpermit/linear-demo/mcp-servers.png b/static/img/mcpermit/linear-demo/mcp-servers.png new file mode 100644 index 000000000..98fe2d6cd Binary files /dev/null and b/static/img/mcpermit/linear-demo/mcp-servers.png differ diff --git a/static/img/mcpermit/linear-demo/no-mcps.png b/static/img/mcpermit/linear-demo/no-mcps.png new file mode 100644 index 000000000..42a81b4a7 Binary files /dev/null and b/static/img/mcpermit/linear-demo/no-mcps.png differ diff --git a/static/img/mcpermit/linear-demo/pm-create-denied.png b/static/img/mcpermit/linear-demo/pm-create-denied.png new file mode 100644 index 000000000..cb24060ab Binary files /dev/null and b/static/img/mcpermit/linear-demo/pm-create-denied.png differ diff --git a/static/img/mcpermit/linear-demo/pm-list-issues.png b/static/img/mcpermit/linear-demo/pm-list-issues.png new file mode 100644 index 000000000..6bd0600c3 Binary files /dev/null and b/static/img/mcpermit/linear-demo/pm-list-issues.png differ diff --git a/static/img/mcpermit/linear-demo/pm-medium-trust.png b/static/img/mcpermit/linear-demo/pm-medium-trust.png new file mode 100644 index 000000000..66cdda5b2 Binary files /dev/null and b/static/img/mcpermit/linear-demo/pm-medium-trust.png differ diff --git a/static/img/mcpermit/linear-demo/tool-trust-levels.png b/static/img/mcpermit/linear-demo/tool-trust-levels.png new file mode 100644 index 000000000..6d560a05a Binary files /dev/null and b/static/img/mcpermit/linear-demo/tool-trust-levels.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/attio-item.png b/static/img/mcpermit/n8n-linear-demo/attio-item.png new file mode 100644 index 000000000..79be498e1 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/attio-item.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/consent-service-select.png b/static/img/mcpermit/n8n-linear-demo/consent-service-select.png new file mode 100644 index 000000000..c60eb7050 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/consent-service-select.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/create-credential.png b/static/img/mcpermit/n8n-linear-demo/create-credential.png new file mode 100644 index 000000000..002320e5e Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/create-credential.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/execution-blocked.png b/static/img/mcpermit/n8n-linear-demo/execution-blocked.png new file mode 100644 index 000000000..de7e25475 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/execution-blocked.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/issue-config.png b/static/img/mcpermit/n8n-linear-demo/issue-config.png new file mode 100644 index 000000000..11af4c163 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/issue-config.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/linear-issue-created.png b/static/img/mcpermit/n8n-linear-demo/linear-issue-created.png new file mode 100644 index 000000000..8ab5f6368 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/linear-issue-created.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/mcp-client-config.png b/static/img/mcpermit/n8n-linear-demo/mcp-client-config.png new file mode 100644 index 000000000..d953b3791 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/mcp-client-config.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/mcp-client-tool-selector.png b/static/img/mcpermit/n8n-linear-demo/mcp-client-tool-selector.png new file mode 100644 index 000000000..5b740981f Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/mcp-client-tool-selector.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/select-save-issue.png b/static/img/mcpermit/n8n-linear-demo/select-save-issue.png new file mode 100644 index 000000000..7432fb23e Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/select-save-issue.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/tool-import.png b/static/img/mcpermit/n8n-linear-demo/tool-import.png new file mode 100644 index 000000000..5f7da3fdd Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/tool-import.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/trust-level-dashboard.png b/static/img/mcpermit/n8n-linear-demo/trust-level-dashboard.png new file mode 100644 index 000000000..40a6a2bc0 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/trust-level-dashboard.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/trust-level-low.png b/static/img/mcpermit/n8n-linear-demo/trust-level-low.png new file mode 100644 index 000000000..a2805780d Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/trust-level-low.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/workflow-complete.png b/static/img/mcpermit/n8n-linear-demo/workflow-complete.png new file mode 100644 index 000000000..4a09924c4 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/workflow-complete.png differ diff --git a/static/img/mcpermit/n8n-linear-demo/workflow-overview.png b/static/img/mcpermit/n8n-linear-demo/workflow-overview.png new file mode 100644 index 000000000..ae1ea0d75 Binary files /dev/null and b/static/img/mcpermit/n8n-linear-demo/workflow-overview.png differ