PER-14219 Linear MCP Gateway Demo (#615)

* Linear MCP Gateway Demo

* updated location of demo in docs

* n8n agent security demo

Author: dshoen619

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."
+    }
+}

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.

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 |

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",
+                },
+              ],
+            },
           ],
         },
       ],