MCP (AI assistants)
Upvora speaks the Model Context Protocol, so Claude and other MCP clients can work in your board as the person using them: search and post ideas, vote, comment and, for your team, run the board. They can never do more than that person can do in Upvora.
Turn it on
- Open Admin, MCP and switch on Enable MCP.
- Choose Who may connect: administrators only (default), administrators and collaborators, or any signed-in member.
- Leave Clients may register themselves on for the usual setup, or turn it off and register specific clients on the same page.
While MCP is off, /mcp answers 404 with {"error":"mcp_disabled"} and the discovery documents are hidden, so an assistant reports that the server is unavailable rather than starting a sign-in.
Connect a client
Add a remote MCP server with your board's address plus /mcp, for example https://feedback.example.com/mcp. The client discovers everything else on its own:
- It registers itself (or uses a client an admin registered).
- You sign in to your board with its normal sign-in, whatever your site offers: email, Google, GitHub, Microsoft or your own OAuth provider.
- You see which application is asking, what it may do and where it returns, and choose Allow or Cancel.
Access tokens last an hour and renew automatically. Blocking someone, changing their role, raising the minimum role, removing the client or turning MCP off ends the connection immediately.
Clients
| Client | What it needs |
|---|---|
| Claude (claude.ai, Claude Desktop, Claude Code) | Works with self-registration. To register it yourself instead, use the return address https://claude.ai/api/mcp/auth_callback (Claude Code uses a http://localhost:<port> address and registers itself). |
| ChatGPT connectors | Register themselves, so keep Clients may register themselves on. |
| Any other MCP client | Self-registration, or a client you register with its exact return address. |
Clients may register themselves is OAuth dynamic client registration (RFC 7591) at /oauth2/register, advertised as registration_endpoint. It is limited to 20 registrations an hour per address and 200 per site; clients that register and are never used are removed after a week.
When you register a client yourself, the return address (redirect URI) must match exactly what the client sends, character for character. It may be https, http on a loopback address (localhost, 127.0.0.1), or an app's own scheme such as cursor://.
Scopes and discovery
| Scope | Grants |
|---|---|
upvora | Everything the person can do in Upvora. |
upvora:read | Reading only: the assistant sees reading tools and nothing else. |
Clients find everything from two documents: /.well-known/oauth-protected-resource (also at /.well-known/oauth-protected-resource/mcp) and /.well-known/oauth-authorization-server. Both exist only while MCP is on.
Tokens
- Authorization codes last 10 minutes and work once.
- Access tokens last an hour and work only at
/mcpon the address they were issued for. - Refresh tokens last 30 days and are replaced on every use, so an assistant you use regularly stays connected. Presenting an old one ends that connection (a stolen copy cannot keep working); the person reconnects once.
What it can do
| Area | Tools |
|---|---|
| Ideas | search, get, find similar, create, edit, set status, privacy, product, internal note, delete (admin) |
| Votes, follows, comments | vote, unvote, list voters, follow, comment, edit, delete, react |
| Submitting ideas | ideation context and submit with an Idea Brief (see below), or delegate to your site's Vora |
| Team and admin | tags, products, statuses, scorecards, users and roles, invitations, webhooks, sign-in providers, every settings page, system status and update |
| You | notifications, your settings, change email |
Each person only sees the tools their role allows; a read-only connection sees only reading tools. Tools that change the whole site say so and ask the assistant to confirm with you first.
Submitting ideas the Vora way
When you ask your assistant to submit an idea, it picks the product with you, fetches that product's interview guidance (the same instructions Vora uses) and the Idea Brief structure, interviews you, shows you the title and brief, and submits after you approve. The idea and its brief look exactly like one submitted through Vora. Clients that support prompts also get a ready-made submit_idea prompt.
Attaching files
upvora_ideas_create and upvora_ai_submit_brief take an attachments list, up to 3 files of 5 MB each: images always, and PDF, .txt and .md where the site allows file attachments. Each item is {upload: {fileName, content}} with the bytes base64-encoded, or for a text or Markdown file {upload: {fileName, text}}. Files go through exactly the same checks as the web form. An assistant can only attach a file whose content it has: Claude Code and agents with file access can attach anything; in a chat, an assistant can attach notes it writes as .md or .txt. Require Vora never blocks MCP.
Deploying
Most assistants run in the vendor's cloud. Part of the connection comes from the person's browser and part comes from the vendor's servers, and the second part must reach your board over the internet:
| Step | Called by | Paths |
|---|---|---|
| Discovery, registration, token exchange and renewal, tool calls | The assistant's servers, over the internet | /.well-known/*, /oauth2/register, /oauth2/token, /mcp |
| Signing in and approving | The person's browser | /oauth2/authorize and your sign-in |
So a VPN on your laptop does not help: the browser half works, then the exchange fails because the vendor cannot reach the board. A board that is not reachable from the internet needs an MCP-only public address (below). Assistants that run on your own machine and network, such as Claude Code, can use the board's own address.
Upvora builds the addresses it hands to clients (the issuer, every endpoint and the /mcp resource) from the address the request arrived on. Behind a reverse proxy, pass X-Forwarded-Proto and keep the original Host (or set X-Forwarded-Host). Responses are plain JSON, never a stream, so proxy buffering does not matter. Changing your board's address disconnects every assistant; each person reconnects once.
Internal boards
For a board that stays on an internal network, give it an MCP-only public address. On the same container set:
MCP_ORIGINS: https://mcp.example.com
MCP_PORT: "3001"
Route the public hostname to port 3001 only, for example a Cloudflare tunnel with mcp.example.com pointing at http://upvora:3001, and do not publish that port anywhere else. Leave BASE_URL as the internal address and keep port 3000 internal.
- Only the connection is public. Everything arriving on
MCP_PORTgets/mcp, the OAuth endpoints, their discovery documents and the consent page with its own scripts and your logo. Every other path (the board, ideas, admin, sign-in, uploads and the REST API) is a404, whatever the request'sHostor forwarded headers say. - Sign-in stays internal. When someone connects, the consent step sends their browser to your board's normal sign-in and back with a single-use code that only that browser can use. That first connection needs a device on your network; after that, the assistant renews from anywhere. The consent page says who is signed in and which address the connection goes through.
- Connections are tied to the address. Codes and tokens issued through the MCP-only address work only there, and the board's own work only on the board.
- Connect assistants to
https://mcp.example.com/mcp. Admin, MCP lists it. - Without
MCP_PORT, Upvora recognises the public hostname fromHostandX-Forwarded-Host. That is only safe behind a proxy that routes by hostname and passesHostthrough unchanged (Cloudflare tunnels do by default). A proxy that rewritesHostto the board's name, or a port3000reachable from the internet, would expose the board, so preferMCP_PORT. - Rate limiting at the edge is a good extra; OAuth and each person's role are what control access. Anyone can see that the public address exists and which sign-in it sends people to.
- Single-site installs only (
HOST_MODE=single). Upvora refuses to start if an entry is not https, has a path, uses a wildcard, an IP address or a trailing dot, repeats another or equalsBASE_URL, or ifMCP_PORTis set withoutMCP_ORIGINS.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
| Claude: "Couldn't register with ... sign-in service" | MCP is off (check Admin, MCP), self-registration is off and the client is not registered, or the assistant cannot reach the board from the internet (see Internal boards). |
/mcp returns 404 mcp_disabled | Turn MCP on in Admin, MCP. |
| "Client registration is disabled on this site; ask an administrator to register the client." | Turn on Clients may register themselves, or register the client yourself. |
| "This application is not registered on this site." | The client was removed (or never used and cleaned up). Reconnect from the assistant. |
| "The application's return address does not match its registration." | The registered redirect URI differs from the one the client sends. They must match exactly. |
| "Your role on this site is not allowed to connect MCP clients." | Raise the person's role or widen Who may connect. |
| "This connection request is invalid or has expired. Start connecting again from your assistant." | Internal boards: signing in took longer than 30 minutes, the link was opened twice or in a different browser from the one that started connecting. Start again from the assistant in one browser. |
| The sign-in page opens, then connecting fails or hangs | The vendor's servers cannot reach the board. Add an MCP-only public address. |
invalid_grant: "The refresh token is invalid, expired, or already used." | The connection ended (30 days unused, a role change or sign-out, or an old token was replayed). Reconnect once. |
An assistant that was working gets 401 at /mcp | The token is for another address (for example the board instead of the MCP-only address), or it was revoked. Reconnect. |
Limits and safety
- Tool calls are budgeted per person and per client, list results are capped at 100, and very long results are cut at 64 KB.
- The assistant is told to treat everything it reads from the board as data, never as instructions.
- Every tool call is recorded in the server log (who, which tool, outcome), without its contents.