Connect an AI agent via MCP

How to get there: Open Settings → Integrations & data → Integrations and open the MCP server card. It shows your portal's MCP URL and a link to this guide. Point your MCP-compatible client at your portal's /mcp URL and it will discover everything else automatically. Step-by-step setup is below for Codex, Claude.ai, Claude Desktop, ChatGPT, Claude Code, Cursor, VS Code, Gemini CLI, Windsurf, Zed, Cline, and Goose.

ProductLift exposes a Model Context Protocol (MCP) server so AI agents can list, create, and update posts, comments, votes, statuses, categories, tags, and users on your portal on your behalf. Every call is authenticated as a real ProductLift user and is scoped to that user's permissions, just like the REST API.

Endpoint

Each portal serves its own MCP endpoint at:

https://your-portal.example.com/mcp

This is a single POST endpoint that speaks JSON-RPC 2.0. Batch requests are supported.

You do not need to hand-configure any tools. The client calls tools/list on connect and discovers every action available to your user.

Authentication

MCP uses OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591). Any MCP-compliant client can register itself, redirect a portal admin to log in, and receive a bearer token scoped to mcp. You do not need to create an API key first.

Two discovery documents drive the flow. Clients fetch them automatically:

  • GET /.well-known/oauth-authorization-server: advertises the authorize, token, and registration endpoints, plus supported grant types (authorization_code, refresh_token) and the S256 PKCE method.
  • GET /.well-known/oauth-protected-resource: tells the client that the /mcp resource trusts this same portal to issue tokens.

Both documents advertise the current portal hostname, so custom domains work out of the box.

The OAuth flow, step by step

  1. The client fetches the two discovery documents from your portal.
  2. The client registers itself by POSTing to /oauth/register (DCR). No pre-shared secret required.
  3. The client opens the browser to /oauth/authorize?... where you log in with your normal portal credentials and approve the connection.
  4. The client exchanges the returned authorization code at /oauth/token for an access token with scope mcp.
  5. Every subsequent MCP request includes Authorization: Bearer <access_token>.

Setting it up in common clients

Every client below does the same thing: you paste your portal's /mcp URL, the client registers itself with your portal, and your browser opens so you can sign in and approve. Replace https://your-portal.example.com/mcp with your own portal URL (custom domains work).

Pick your client:

A client must support the browser sign-in (the MCP OAuth flow) to connect. Your portal only issues MCP tokens through that sign-in screen, so clients that can only send a pasted token, such as GitHub Copilot CLI at the time of writing, cannot connect yet.

Codex

The Codex desktop app, CLI, and IDE extension use the same MCP configuration file.

In the Codex desktop app:

  1. Open Plugins and select the MCPs tab.

  2. Open Add and choose the option to connect a custom MCP.

  3. Enter ProductLift as the Name.

  4. Select Streamable HTTP as the Type.

  5. In URL, enter your full portal address followed by /mcp, for example https://your-portal.example.com/mcp. Replace the example with your own portal address.

  6. Leave Bearer token env var, Headers, and Headers from environment variables empty. ProductLift uses browser sign-in, so you do not need to paste an API key or token.

    Codex custom MCP setup with ProductLift as the name, Streamable HTTP selected, and a portal MCP URL

  7. Click Save. If Codex asks you to restart, do so.

  8. Select Authenticate if the server needs sign-in. In the browser, sign in to ProductLift and approve the connection. If no sign-in window opens, run codex mcp login productlift in a terminal (use the server name you saved).

In the IDE extension: Open the gear menu, choose MCP servers, then Add server. Choose Streamable HTTP, name the server productlift, and enter your portal's /mcp URL. Save, select Restart extension, then Authenticate.

For more details, see the official OpenAI MCP documentation.

From the terminal (Codex CLI):

codex mcp add productlift --url https://your-portal.example.com/mcp
codex mcp login productlift

The second command opens your browser for the sign-in. codex mcp list afterwards shows the server as connected.

Or edit the config file directly. Add this to ~/.codex/config.toml:

[mcp_servers.productlift]
url = "https://your-portal.example.com/mcp"

OAuth is Codex's default for streamable HTTP servers, and Codex registers itself with your portal automatically, so you do not need an auth line, a client ID, or a token. Run codex mcp login productlift once to sign in.

Claude.ai

  1. In Claude.ai, open Settings → Connectors and click Add custom connector.

  2. Give it a name, for example "ProductLift", and paste your portal's /mcp URL, for example https://your-portal.example.com/mcp.

    Add custom connector dialog in Claude.ai

  3. Two groups of settings appear, Authentication and OAuth client. Claude checks your portal and fills both in for you, marking its choices Detected. Leave them exactly as they are. You do not need to add any headers or open the Advanced section.

  4. Click Add. ProductLift now appears in your connectors list as a Web connector.

    ProductLift listed among Claude.ai connectors

  5. Open it and click Connect.

    Claude.ai connector detail with Connect button

  6. A window opens on your portal. Sign in with your normal portal credentials if asked, then approve the requested mcp scope.

    ProductLift OAuth authorize screen requesting the mcp scope

After you approve, Claude.ai discovers every tool the connector exposes (posts, comments, votes, statuses, etc.). Use the tool permissions view to decide which ones run automatically and which require confirmation. We recommend leaving anything that deletes on "ask first".

Claude.ai tool permissions for the ProductLift connector

Claude Desktop

Claude Desktop uses the same connector settings as Claude.ai. Open Settings → Connectors, click Add custom connector, paste https://your-portal.example.com/mcp, and follow the same steps as above. Claude Desktop opens the sign-in in its own browser window; after you approve, it stores the token and the connection persists across restarts.

ChatGPT

Custom MCP servers in ChatGPT require Developer mode, available on Plus, Pro, Business, Enterprise, and Edu plans. In a managed workspace an admin first has to allow custom connectors (Workspace Settings → Permissions & Roles → Connected Data).

  1. Open Settings → Security and login and turn on Developer mode. (Older builds keep this switch under Settings → Apps → Advanced settings.)
  2. Open Settings → Connectors and click Create. (Newer builds call this page Plugins, reachable at chatgpt.com/plugins; click the plus button.)
  3. Enter a name and a short description. ChatGPT reads the description when deciding whether to use the connector, so something like "Manage feedback posts, votes, and roadmap on our ProductLift portal" works well.
  4. Paste https://your-portal.example.com/mcp as the MCP server URL and set Authentication to OAuth.
  5. Create the connector. ChatGPT discovers your portal's OAuth settings, registers itself, and opens your portal so you can sign in and approve.

To use it in a chat, enable the connector under the tools (plus) menu of the conversation.

Claude Code

Add the server once for all your projects, then sign in from inside Claude Code:

claude mcp add --transport http --scope user productlift https://your-portal.example.com/mcp

Start Claude Code, type /mcp, pick productlift, and choose Authenticate. Your browser opens for the sign-in. Drop --scope user if you only want the connection in the current project.

Cursor

  1. Open Cursor Settings → Tools & MCP (older versions: MCP) and click New MCP Server. This opens ~/.cursor/mcp.json.
  2. Add the server:

{
  "mcpServers": {
    "productlift": {
      "url": "https://your-portal.example.com/mcp"
    }
  }
}

  1. Back in the settings list the server shows Needs login or Connect. Click it, sign in to your portal, and approve.

VS Code

  1. Open the Command Palette and run MCP: Add Server.
  2. Choose HTTP (HTTP or Server-Sent Events), paste https://your-portal.example.com/mcp, name it productlift, and pick Global so it is available in every workspace.
  3. VS Code asks whether to allow the server to authenticate. Allow it, sign in to your portal, and approve.

This writes the entry to your user mcp.json. If you prefer to add it by hand, or want to share it with a team in .vscode/mcp.json:

{
  "servers": {
    "productlift": {
      "type": "http",
      "url": "https://your-portal.example.com/mcp"
    }
  }
}

Gemini CLI

Add the server to ~/.gemini/settings.json:

{
  "mcpServers": {
    "productlift": {
      "httpUrl": "https://your-portal.example.com/mcp",
      "oauth": { "enabled": true }
    }
  }
}

Start Gemini CLI and run /mcp auth productlift. Your browser opens for the sign-in. Run the same command again if the token ever expires.

Windsurf

Windsurf (also sold as Devin Desktop) keeps its MCP servers in ~/.codeium/windsurf/mcp_config.json. Open it from the MCPs icon in the top right of the Cascade panel (or Settings → Cascade → MCP Servers) and add:

{
  "mcpServers": {
    "productlift": {
      "serverUrl": "https://your-portal.example.com/mcp"
    }
  }
}

Save and refresh the MCP list. Windsurf opens your portal in the browser for the sign-in. Note the key is serverUrl, not url.

Zed

  1. Open Settings → AI → MCP Servers (or run agent: open settings from the command palette and choose MCP Servers).
  2. Click Add Server, then Add Remote Server, and paste https://your-portal.example.com/mcp.

Or add it to your Zed settings.json by hand:

{
  "context_servers": {
    "productlift": {
      "url": "https://your-portal.example.com/mcp"
    }
  }
}

Because there is no Authorization header configured, Zed prompts you to sign in to your portal the first time it connects.

Cline

  1. Click the MCP Servers icon in the Cline panel and open the Remote Servers tab.
  2. Enter productlift as the server name, https://your-portal.example.com/mcp as the server URL, and choose Streamable HTTP as the transport type.
  3. Click Add Server. Cline opens your portal in the browser for the sign-in.

The entry in Cline's cline_mcp_settings.json looks like this. The transport type must be spelled streamableHttp exactly, otherwise Cline falls back to the older SSE transport, which the portal does not serve:

{
  "mcpServers": {
    "productlift": {
      "type": "streamableHttp",
      "url": "https://your-portal.example.com/mcp"
    }
  }
}

Browser sign-in for remote servers arrived in Cline in August 2026, so update Cline if you see no sign-in window.

Goose

  1. In the Goose desktop app, open the sidebar, click Extensions, then Add custom extension.
  2. Choose Remote Extension (Streamable HTTP), name it productlift, and paste https://your-portal.example.com/mcp as the endpoint.
  3. Save. Goose opens your portal in the browser for the sign-in.

From the terminal, run goose configure, choose Add Extension, then Remote Extension (Streamable HTTP), and enter the same URL. Goose registers itself with your portal automatically, so leave client ID and secret empty.

Other MCP-compatible clients

Continue, JetBrains AI Assistant, Perplexity, Raycast, and most other AI tools that support remote MCP servers work the same way: look for "MCP server", "remote server", "connector", or "extension" in the client's settings, paste https://your-portal.example.com/mcp as the server URL, choose Streamable HTTP if asked for a transport, and choose OAuth if asked for an authentication type. The client discovers the OAuth endpoints via the two well-known documents and prompts you to log in. If the client offers no way to sign in through the browser, it cannot connect to ProductLift yet.

What the AI can do

The MCP tool list is generated from the same OpenAPI spec that powers the REST API docs. Anything the API can do, an MCP client can do, including:

  • List, create, update, and delete posts
  • Upload images and files and place them inside post text
  • Change post status, category, tags, and assignees
  • List and post comments
  • List and cast votes (including vote-on-behalf of end users)
  • Manage statuses, categories, tags, and boards
  • List and update users

Each tool carries a machine-readable description and an example payload so the AI does not have to guess parameter shapes.

Images and files in changelog posts

You can ask your AI assistant: "Create a draft changelog post. Put this screenshot after the first paragraph and add the PDF download link below the changes."

The assistant needs access to the files you want to upload. Uploads are available to portal admins, with a limit of 10 MB per file. Supported images are JPG, PNG, GIF and WebP. Supported files are PDF, TXT, CSV, Word, Excel, PowerPoint, ZIP, MP3 and MP4. Uploaded links use public storage, just like images added in the editor. Use them for content you want to share with readers.

The assistant uses these steps:

  1. Create a draft with posts.create, or find the existing post with posts.get.
  2. Call posts.upload for each file. Send the post's key, kind (image or file), filename and the file bytes in content_base64. An optional label sets the image's alt text or the file's link text.
  3. Insert the returned html or markdown snippet at the requested place in the full post text. Use the post's editor_type, falling back to the portal setting from portal.get.
  4. Save the full text with posts.update, keeping the other text in place. Preview the draft before publishing.

Images appear between the chosen paragraphs. They do not become the post's header image. Files get a download link and also appear in the post's attachments. Uploading a file does not publish the post or change its text by itself.

The REST API offers the same upload through POST /api/v1/posts/{key}/uploads, using the same JSON fields.

Edit your knowledge base with AI

The same ZIP workflow as Edit Knowledge Base with AI is available through MCP. For example: "Export my knowledge base, update the installation guide with these steps and screenshots, and show me the proposed changes."

The assistant can use this workflow:

  1. knowledgebase.export returns a temporary download link for a ZIP with articles, section details, images and editing instructions. The assistant downloads the file directly. Downloads support resuming or requesting byte ranges.
  2. After editing, knowledgebase.startUpload returns upload links for parts of 3 MB. A local script sends each part directly to its link, in order. The file bytes stay outside the conversation. Retrying an identical part is safe.
  3. knowledgebase.completeUpload checks the full size and checksum to confirm the ZIP arrived correctly. The file reference can then be used for preview and import.
  4. knowledgebase.previewSync lists proposed additions, updates and deletions. It uses the file already on the server, without saving articles or uploading images.
  5. After you approve the preview, knowledgebase.executeSync applies the same file reference with the latest preview_key and confirm_changes=true. It updates existing articles and publishes new ones. Selected deletions also need confirm_deletions=true after your explicit approval. Each preview key can be used once. If live content changes after the preview, request a new preview and approve it again.
  6. knowledgebase.discardArchive removes the temporary file and invalidates its links. Imported articles and images stay in place.

The tools need the knowledge base board's integer tab_id, available from tabs.list. Upload setup also needs the ZIP's size_bytes and sha256, which the assistant calculates locally. Preview and import use the returned archive_key, rather than sending the ZIP again. Keep the exported file structure and article filenames. Put images in the ZIP and refer to them with relative Markdown paths. The import uploads the images and replaces those paths in the article text.

Articles or sections missing from the ZIP are kept by default. To remove them, the assistant must send the specific IDs shown in the preview as delete_confirmed or delete_sections_confirmed. Deleting a section also removes its articles. Only authorize those lists after checking the preview.

This workflow is available to portal admins and supports ZIPs up to 100 MB, just like the normal upload screen. Each upload part stays small. Temporary files and links expire after one hour and belong to the user and board that created them. Treat the links as private. The AI client needs a local script or HTTP client to transfer files directly; it does not need your API credentials for the temporary links.

If an upload stops, start it again with the same size and checksum within that hour. The server returns the existing reference and progress, so the assistant can continue at the first part whose offset is at least received_bytes. There can be five temporary archives per portal at a time. Discard unused references when finished. Expired or orphaned files are checked every ten minutes, so they do not depend on someone starting another upload to be removed.

The REST API offers the same workflow under /api/v1/knowledgebase/sync/archive: GET exports, POST /uploads starts an upload, POST /uploads/complete completes it, POST /preview previews, POST /execute imports and DELETE discards the temporary archive. The existing ZIP download and multipart upload routes stay available for browser clients.

Permissions and audit

MCP calls are attributed to the user who approved the connection. If that user only has member access, the AI can only see what a member sees. If they have admin access, the AI can perform admin actions. Every action taken shows the same author, activity trail, and notifications as if the user had done it themselves in the UI.

To revoke access, remove the token from the OAuth clients list in your portal, or revoke it from the client side.

Troubleshooting

  • 401 Unauthorized on /mcp: the access token is missing, expired, or was issued for a different portal. Reconnect from the client to trigger a fresh OAuth flow.
  • Method Not Allowed on GET /mcp: this is expected. The endpoint only accepts POST. Some clients send a GET liveness probe on connect; the JSON-RPC error response is the correct behaviour.
  • Codex lists the server but shows no tools: the sign-in did not complete. Run codex mcp login productlift in a terminal, then restart the app or extension.
  • ChatGPT has no Create button on the connectors page: Developer mode is off, or your workspace admin has not allowed custom connectors. See the ChatGPT steps above.
  • Client can't find the OAuth endpoints: check that your portal hostname resolves publicly. MCP clients cannot use hostnames only reachable behind a corporate VPN unless the AI itself runs inside the same network.