Overview
Bring Your Own MCP (BYOM) lets your organization plug an external MCP (Model Context Protocol) server into Minoa. Once connected, the tools, resources, and prompts exposed by your MCP server become available to Minoa’s AI agents — so Minoa can pull in your product analytics, internal knowledge, support data, warehouse queries, or anything else you already expose over MCP.What you can do with BYOM
Once an external MCP server is connected and enabled, the tools it exposes become available to Minoa’s research agent — the agent that handles account research and generates account overviews. You’ll see connected servers surfaced in the Business Case Copilot’s context panel, and the agent will call those tools alongside Minoa’s built-in research flow when relevant to a deal. When Minoa connects to your server it runs the standard MCP handshake, caches the discovered capabilities, and re-discovers on demand from the server detail view.Requirements
Before connecting a server, make sure:- The server supports MCP protocol version 2024-11-05 (Minoa initializes MCP sessions with that version).
- It is reachable over the public internet at an HTTPS URL.
- It accepts MCP JSON-RPC requests over HTTP. Minoa POSTs to the server’s base URL, with
/mcp,/rpc, and/jsonrpcused as fallbacks if the base URL doesn’t accept POST directly. - You have admin permissions in your Minoa workspace to add or modify MCP servers.
Authentication modes
Minoa supports three authentication modes. The mode you choose affects how credentials are scoped:| Auth Type | Credential Scope | When to use |
|---|---|---|
| None | Org-shared | Public MCP servers that don’t require auth |
| API Key | Org-shared | Servers that accept a bearer token or X-API-Key header. Stored once per workspace and used by all users. |
| OAuth 2.0 | Personal (per user) | Servers that require each user to authenticate as themselves. Every user connects individually and Minoa uses their own token when they trigger an agent. |
API Key details
When API Key is selected, Minoa attaches the key as bothAuthorization: Bearer <key> and X-API-Key: <key> on every request, so most common server conventions work out of the box. The key is stored once at the org level and reused for all requests.
OAuth 2.0 details
For OAuth servers, Minoa implements the MCP OAuth profile:- Discovery — Minoa fetches
/.well-known/oauth-authorization-server(RFC 8414) on the MCP server’s origin to locate authorization, token, and registration endpoints. - Dynamic client registration — If the server advertises a
registration_endpoint(RFC 7591), Minoa will register itself automatically. If dynamic registration isn’t available, contact Minoa support to register a client manually for your server. - Authorization Code + PKCE — Minoa uses PKCE for all OAuth flows; the PKCE verifier never leaves Minoa.
- Per-user tokens — Each user who wants to use an OAuth-backed server initiates their own OAuth flow from the server details view and is redirected through your server’s consent screen. Their access token (and refresh token, if provided) is stored against their user account, never shared.
- Automatic token refresh — Minoa proactively refreshes OAuth tokens before they expire and retries once on a
401response. When a refresh is no longer possible, the server is markedneedsAuthand the user is prompted to re-authenticate.
Connecting a server
Open the Integrations panel
Go to Settings → Integrations. If BYOM is enabled for your workspace, you’ll see a MCP Servers section. Click Add MCP Server.
Enter the basics
Provide a name, the server URL (HTTPS), and an optional description and tags. Tags are displayed as badges on the server card for quick visual categorization (for example
analytics, support, warehouse).Choose an auth type
Pick None, API Key, or OAuth. For API Key, paste the key. For OAuth, you’ll be redirected to your server to sign in and authorize Minoa in the next step.
Test the connection
Minoa initializes the MCP handshake and discovers the server’s tools, resources, and prompts. You’ll see counts for each once discovery completes.
Server configuration options
Each connected server supports a few extra fields you can edit from the server detail view:- Agent instructions — Free-form guidance added to Minoa’s research agent whenever this server is available. Use this to explain how to map Minoa’s deal context to entities in your system, which tools to prefer, naming conventions, etc.
- Sample questions — A short list of example prompts that appear in the Business Case Copilot’s research panel as quick-start suggestions, so users know what this server can answer.
- Auto-generated starting points — The first time Minoa discovers a server’s tool surface, it will draft initial agent instructions and sample questions for you. You can freely edit both.
Security & credential handling
- Credential scope — For None and API Key auth, credentials are stored once at the workspace level and used by all of your users. For OAuth, credentials are per-user; each member of your workspace authenticates individually and Minoa only ever uses their own tokens for their own requests.
- HTTPS only — MCP server URLs must be HTTPS, and Minoa validates outbound requests to prevent access to private networks and cloud metadata endpoints.
- Server-side credentials — API keys, access tokens, and refresh tokens are never returned to the browser. They are stored server-side and only used to make requests to your MCP server.
- Audit trail — Every change to an MCP server connection is audited with the acting user.
Connection states
An MCP server will be in one of the following states in the UI:| Status | Meaning |
|---|---|
connected | Server is reachable, capabilities have been discovered, Minoa’s agent can call it |
needsAuth | The server requires authentication (or OAuth tokens expired and couldn’t be refreshed). User action required. |
error | The last connection attempt failed — the error message is shown on the server card |
disabled | The server is saved but turned off. Minoa’s agent will not use it until it is re-enabled. |
Troubleshooting
”OAuth client registration failed”
The MCP server’s OAuth metadata did not expose a dynamic registration endpoint (RFC 7591), or registration was rejected. You’ll need to manually register a client with your OAuth provider and provide the client ID / secret through Minoa support.”Authentication expired. Please re-authenticate.”
An access token has expired and the refresh token is no longer accepted. Open the server’s menu and click Re-authenticate to re-run the OAuth flow.Minoa’s agent doesn’t seem to use my tools
- Confirm the server’s status is
connected(notneedsAuth/disabled/error). - Click Discover Capabilities on the server card to re-pull the tool list.
- Make sure each tool exposes a meaningful
description— Minoa’s agent uses descriptions to decide when to call a tool.
Connection test reports 401
Minoa will attempt one automatic token refresh on a 401 before surfacing the error. If it still fails, either your API key is wrong, the OAuth token is truly revoked, or the server doesn’t acceptAuthorization: Bearer <key> / X-API-Key — in which case reach out to support.