Connect an AI agent via MCP

How to get there: MCP is a per-portal endpoint. There is no admin screen to configure it. Point your MCP-compatible client (Claude Desktop, Cursor, ChatGPT, etc.) at your portal hostname and it will discover everything else automatically.

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

Claude.ai (custom connector)

In Claude.ai, open Settings → Connectors and click Add custom connector. Paste your portal's /mcp URL, for example https://your-portal.example.com/mcp.

Add custom connector dialog in Claude.ai

Once added, ProductLift appears in your connectors list as a Web connector.

ProductLift listed among Claude.ai connectors

Open it and click Connect to start the OAuth flow.

Claude.ai connector detail with Connect button

Claude.ai opens a browser window on your portal to authorize the connection. Log in with your normal portal credentials and 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.

Claude.ai tool permissions for the ProductLift connector

Claude Desktop

Add a remote MCP server entry pointing at your portal's /mcp URL. Claude Desktop handles the OAuth dance in its own browser window; after you approve, it stores the token and the connection persists across restarts.

Cursor / ChatGPT / other MCP-compatible clients

The setup is the same: paste https://your-portal.example.com/mcp as the server URL. The client discovers the OAuth endpoints via the two well-known documents and prompts you to log in.

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
  • 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.

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.
  • 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.
Made with ProductLift