diff --git a/docs/home.mdx b/docs/home.mdx index 2d2bb8d3..7a93173f 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -19,6 +19,7 @@ import PageVerticalPadding from "../src/components/home-page/PageVerticalPadding import Container from "../src/components/home-page/Container"; import Hr from "../src/components/home-page/Hr"; import { + mcpGatewayRow, firstRow, quickStartRow, policyModelingRow, @@ -39,6 +40,8 @@ import { +
+
diff --git a/docs/permit-mcp-gateway/index.mdx b/docs/permit-mcp-gateway/index.mdx index 491287a4..33d35a80 100644 --- a/docs/permit-mcp-gateway/index.mdx +++ b/docs/permit-mcp-gateway/index.mdx @@ -47,8 +47,9 @@ See [Permit.io Integration](/permit-mcp-gateway/permit-integration/) for the det ## Start Here -1. Read the [**Overview**](/permit-mcp-gateway/overview/) to understand what the gateway enforces and when to use it -2. Follow the [**Getting Started Guide**](/permit-mcp-gateway/guide/) to set up your first gateway and make your first authorized tool call +1. Follow the [**Quick Start**](/permit-mcp-gateway/quickstart/) to get a secured gateway URL for any MCP server in under 5 minutes +2. Read the [**Overview**](/permit-mcp-gateway/overview/) to understand what the gateway enforces and when to use it +3. Follow the [**Getting Started Guide**](/permit-mcp-gateway/guide/) for the full walkthrough including trust levels, user management, and audit logs ## Go Deeper diff --git a/docs/permit-mcp-gateway/quickstart.mdx b/docs/permit-mcp-gateway/quickstart.mdx new file mode 100644 index 00000000..7d27ff28 --- /dev/null +++ b/docs/permit-mcp-gateway/quickstart.mdx @@ -0,0 +1,133 @@ +--- +title: Quick Start +sidebar_label: Quick Start +description: Get a secured MCP Gateway URL in under 5 minutes — with or without pre-importing MCP servers. +sidebar_position: 0 +--- + +# Quick Start + +Get a secured gateway URL for any MCP server in under 5 minutes. Every tool call through this URL is authenticated, authorized, and audited — no code changes required. + +## 1. Create an account and a host + +1. Sign up at [app.agent.security](https://app.agent.security) +2. Connect your [Permit.io](https://app.permit.io) organization with an [organization-scoped API key](https://app.permit.io/settings/api-keys) +3. Go to **Dashboard → Create Host** — pick a subdomain, project, and environment + +Your gateway base URL is now live: + +``` +https://.agent.security/mcp +``` + +## 2. Get a gateway URL for your target MCP server + +There are two ways to route traffic through the gateway to an upstream MCP server. Pick the one that fits your setup. + +### Option A: Dynamic MCP (quickest path) + +If you enable **Dynamic MCPs** on your host, you can point to _any_ MCP server by appending a query parameter — no need to pre-import it. + +1. In [app.agent.security](https://app.agent.security), go to your host's **Settings** and toggle **Allow Dynamic MCPs** on +2. Build your gateway URL by appending `?upstream_mcp=` with the target server's URL: + +``` +https://.agent.security/mcp?upstream_mcp= +``` + +**Examples:** + +| Target MCP server | Gateway URL | +| --- | --- | +| Linear | `https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp` | +| GitHub | `https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://api.githubcopilot.com/mcp/` | +| A custom server | `https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://internal.example.com/mcp` | + +:::warning +Dynamic MCPs let users connect to any MCP server, bypassing the admin allow-list. Only enable this if your organization is comfortable with that. You can disable it at any time. +::: + +### Option B: Pre-imported MCP server + +If you want admin control over which servers are available, import the server first and then use the base URL or a pre-selected URL. + +1. Go to [**MCP Servers → Create Server**](https://app.agent.security/mcp-servers) +2. Enter the upstream URL (e.g., `https://mcp.linear.app/mcp`) and click **Connect** +3. Review the auto-classified tools, adjust trust levels if needed, and click **Import** +4. Grant yourself (or your users) access on the [**Humans**](https://app.agent.security/humans) page + +Your gateway URL is the host base URL — users pick the server during consent: + +``` +https://acme-brave-coral-37.agent.security/mcp +``` + +To skip the server-selection step, append the upstream URL as a query parameter or use a path-based URL: + +``` +https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp +``` + +``` +https://acme-brave-coral-37.agent.security/mcp/linear +``` + +## 3. Connect your MCP client + +Paste the gateway URL into your MCP client config. Replace the example URL with your own. + +### Cursor / VS Code + +Add to `.cursor/mcp.json` (Cursor) or your VS Code MCP settings: + +```json +{ + "mcpServers": { + "linear": { + "url": "https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp" + } + } +} +``` + +### Claude Desktop + +Add to your Claude Desktop config file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows): + +```json +{ + "mcpServers": { + "linear": { + "url": "https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp" + } + } +} +``` + +### Claude Code + +```bash +claude mcp add linear \ + --url "https://acme-brave-coral-37.agent.security/mcp?upstream_mcp=https://mcp.linear.app/mcp" +``` + +## 4. Authenticate and use + +On first connection, your MCP client opens a browser for the consent flow: + +1. **Sign in** — create an account or log in +2. **Select the MCP server** — pick the server you want to connect to (or it is pre-selected if you used `upstream_mcp`) +3. **Set a trust level** — choose what your agent is allowed to do (read, write, or destructive actions) +4. **Accept** — your agent is now connected through the gateway + +Every tool call is now authenticated, authorized by trust level, and logged. Ask your agent to perform an action (e.g., "list my Linear issues") and verify it works. + +--- + +## What's next? + +- [**Getting Started Guide**](/permit-mcp-gateway/guide/) — full walkthrough including trust levels, user management, and audit logs +- [**n8n + Linear demo**](/permit-mcp-gateway/demos/n8n-linear-mcp-gateway) — end-to-end example with an n8n workflow +- [**Platform Reference**](/permit-mcp-gateway/platform/) — admin UI for managing hosts, servers, and users +- [**Overview**](/permit-mcp-gateway/overview/) — security model, architecture, and how it compares to existing tools diff --git a/sidebars.js b/sidebars.js index c6d04ec4..72d90cce 100644 --- a/sidebars.js +++ b/sidebars.js @@ -203,6 +203,7 @@ const sidebars = { label: "Permit MCP Gateway", link: { type: "doc", id: "permit-mcp-gateway/index" }, items: [ + "permit-mcp-gateway/quickstart", "permit-mcp-gateway/overview", "permit-mcp-gateway/guide", "permit-mcp-gateway/platform", diff --git a/src/components/home-page/home-cards-links.js b/src/components/home-page/home-cards-links.js index 979fd2e6..bc708fa4 100644 --- a/src/components/home-page/home-cards-links.js +++ b/src/components/home-page/home-cards-links.js @@ -1,5 +1,29 @@ import React from "react"; +export const mcpGatewayRow = [ + { + type: "link", + href: "/permit-mcp-gateway", + label: "MCP Gateway", + svgIcon: , + description: "Secure any MCP server with auth, consent, and audit — no code changes", + }, + { + type: "link", + href: "/permit-mcp-gateway/guide", + label: "Getting Started", + svgIcon: , + description: "Set up your first gateway and make an authorized tool call in minutes", + }, + { + type: "link", + href: "/permit-mcp-gateway/demos", + label: "Demos & Examples", + svgIcon: , + description: "Step-by-step walkthroughs with Linear, n8n, and more", + }, +]; + export const firstRow = [ { type: "link",