MCP servers

MCP (Model Context Protocol) servers give Assistants access to remote tools and data. A server belongs to either one project or its organization, and you can link the same server to multiple Assistants.

Server scopes

Scope	Availability	Management
Project	Assistants in the owning project	Project administrators
Organization	Assistants in every project in the organization	Organization administrators

Project-scoped servers display a Project · project name badge. Organization-scoped servers display an Organization badge. These badges also appear in the Assistant server selector and tool panels.

Open the server catalog from either location:

• Project settings → AI → MCP servers shows the project's servers and the servers inherited from its organization.
• Organization settings → AI → MCP servers shows the organization's shared servers.

If you are also an organization administrator, the project catalog includes an Organization settings shortcut.

Permissions

Action	Required role
Create a project server	Project administrator, with project MCP creation allowed by the organization
Edit, synchronize, or delete an existing project server	Project administrator
Create, edit, synchronize, or delete an organization server	Organization administrator
Move a server between project and organization scope	Project administrator and organization administrator

Organization and project roles are independent. For example, a project administrator can use an inherited organization server but cannot edit it unless they are also an organization administrator.

Create a server

1. Open Project settings → AI → MCP servers or Organization settings → AI → MCP servers.
2. Select Add MCP server.
3. Enter the server details. When you leave the URL field, MINEO probes the server and fills in Authentication for you; change it if needed.
4. Select Test to verify the endpoint and preview its tools.
5. Save the server. MINEO indexes its tools right away and opens the server page in a new tab.

The form is organized in three sections.

General

Field	Description
Identifier	A recognizable identifier, unique within the selected scope. Models use it to call the server, so it must start with a letter and contain only letters, numbers, and underscores — no spaces or accents.
Description	Optional context that helps users identify the server.
Scope	Project or Organization. This selector is available when you administer both scopes; otherwise MINEO uses the scope you can manage.

Connection

Field	Description
URL	The remote MCP endpoint, including https://. Leaving the field triggers the authentication probe.
Authentication	Auto-detect (default) probes the URL and picks the mode the server requires; a Detected tag confirms it. You can also choose it yourself: no authentication, a shared static token, per-user identity, or OAuth 2.1 (per-user). Each option shows an info icon that explains it. See Authentication.
Authorization token	Static token only. The shared bearer token sent on every call.
Scopes	OAuth only. Scopes to request, entered as tags (press space or Enter after each one). Leave empty to request the scopes the server declares, or openid as a minimum.
Your connection	OAuth only, on a saved server. Connect your account starts the provider consent flow; once connected it shows Connected as account, Disconnect, and a Your connections link to your profile. See Connect with OAuth.

Advanced — rarely needed; both panels are collapsed by default.

Field	Description
Custom headers	Extra headers the remote server requires. Use + in the panel header to add a key/value pair.
Manual client registration	OAuth only. Client ID and Client secret for providers without dynamic client registration; leave them empty otherwise. See Providers without dynamic client registration.

Fill the URL from a Live App

To connect a MINEO Live App, select Fill from LiveApp next to URL, then choose an available app. MINEO fills the app's public URL and main path. You can start a hibernated app or open its details from the same selector.

Automatic wake-up of hibernated Live Apps

When a server URL points to a MINEO Live App with On-demand availability, MINEO wakes the app automatically whenever it is needed:

• In chats, the Assistant wakes the app before connecting and shows a "Waking up LiveApp…" step in the reasoning chain while it starts (up to two minutes).
• Test and Sync also wake the app; the request waits a few extra seconds while it boots.

If the Live App is stopped, or hibernated without On-demand availability, the Assistant shows it as unavailable and Test/Sync return an explanatory error instead of a timeout. Apps created from the FastMCP preset or the MCP Template come with On-demand availability enabled.

The server page

Opening a server from the catalog (click its card, or Edit in its menu) shows its own page with three tabs. The page header shows when the tools were last synchronized, plus Sync and Save.

• Configuration — the same form as when creating the server. Save stores the changes and, when connection settings changed, re-indexes the tools.
• Tools — every indexed tool, with a search box. Expand a tool to read its description and parameters. Each row has Schema, which opens the raw input and output JSON schema in a dialog, and Call, which opens a form generated from the tool's input schema so you can run the tool by hand and inspect the result. Manual calls use your own credentials and are recorded in the call log.
• Call log — every call made to the server, from Assistants or by hand: tool, user, Assistant, status, duration and when it ran. Expand a row to see the arguments and the response. Filter by status, search by tool name or error, and use the toolbar refresh to reload.

Test and synchronize tools

Test, in the create form, contacts the remote server and previews its current tool definitions without storing them. On a saved server there is no separate test: Save re-indexes the tools whenever the connection settings change, and Sync in the page header re-indexes them on demand.

MINEO indexes the tool catalog automatically when the server is created or its connection settings change, when a user connects an OAuth server, and when an Assistant links a server that has never been indexed. If the server cannot be reached at that moment, the server is still saved and MINEO shows a warning; use Sync to retry.

For OAuth servers, Sync uses the credentials of the user who runs it: connect your account first, otherwise it stops with a message asking you to connect.

Each synchronization:

• adds newly exposed tools;
• refreshes existing tool descriptions and input schemas;
• preserves the permission already assigned to each tool;
• marks tools that disappeared from the remote server as unavailable.

Changing the server URL, authentication mode, token, scopes, client ID, or custom headers clears the stored tool catalog and re-indexes it on save. Changing the URL of an OAuth server also removes every user's connection and the registered client; each user must connect again.

Organization project policy

Organization administrators can allow or restrict project MCP server creation from Organization settings → Projects. The toolbar's Default permissions action sets organization defaults. Configure in each project's Permissions column opens an editor with Inherit / Allow / Restrict for every policy; the same action is also available from the row menu. Inheriting projects follow changes to the organization default immediately, while explicit project overrides remain unchanged.

Restriction applies only to creating project-owned servers. Existing servers and Assistant links continue to work, and organization administrators can still create organization-owned servers. Subscription plan availability remains the first requirement; a project policy cannot enable MCP when the plan excludes it.

Change a server's scope

You can move a server between project and organization scope without changing its identity or endpoint:

1. Open Project settings → AI → MCP servers.
2. Open the server page.
3. Select the new Scope in the Configuration tab.
4. Review any impact warning and save.

You must be both a project administrator and an organization administrator. A server identifier must remain unique in the target scope.

• Moving a project server to the organization makes it available to every project in the organization.
• Moving an organization server to the current project requires project MCP creation to be allowed. It removes the server from Assistants in other projects. MINEO shows the affected links and requires confirmation before applying the change. Links to Assistants in the target project remain intact.

Link servers to an Assistant

1. Open an Assistant and select Integrations → MCP.
2. Open the MCP servers selector.
3. Choose one or more servers from the Project and Organization groups.

The link is stored as soon as you change the selection, like the Assistant's attachments: the server's tools and their permissions are available right away, without saving the Assistant. Removing a server from the selector also removes the link (and its per-tool permissions) immediately.

Use the scope badge to distinguish servers with the same identifier. If a server does not exist yet and project creation is allowed, select Add MCP server to create it inline: it is linked to the Assistant and its page opens in a new tab. Organization administrators can still create an organization-scoped server when project creation is restricted. Select Manage to open the project server catalog or Reload to refresh the available servers.

Each linked server panel shows its scope, synchronization status, and tools. Use Synchronize on a panel to re-index its tools and verify that the Assistant can reach the server.

Tool permissions

Expand a synchronized tool to choose how the Assistant may use it:

Permission	Exposed to the model	Behavior
Always approve	Yes	The Assistant can run the tool automatically. This is the default.
Ask every time	Yes	The user must approve each tool call before it runs.
Deny	Yes	The Assistant knows the tool exists, but MINEO refuses the call and tells the model it is not authorized.
Hide	No	The tool is not listed to the model at all.

Deny and Hide both prevent the tool from running; the difference is what the model knows. With Deny, an Assistant asked to delete a customer answers that it cannot delete customers. With Hide, it never learns the tool exists and may look for a workaround with the tools it does have.

Permissions are configured per Assistant. The same tool can therefore be automatic in one Assistant, require confirmation in another, and be denied in a third. Tools marked as unavailable cannot be enabled until the server exposes them again and you synchronize it.

Authentication

Mode	Behavior
No authentication	Sends no Authorization header. Use this for public servers.
Static token	Sends the same shared token as Authorization: Bearer <token> on every call.
Per-user identity	MINEO sends a short-lived signed token that identifies the user making the call. No shared token is required.
OAuth 2.1 (per-user)	Each user authorizes the server once with their own account. MINEO stores their tokens encrypted and refreshes them automatically. See Connect with OAuth.

With Per-user identity, the server verifies the token against MINEO's public key and cannot mint identities itself. See Per-user authenticated MCP to build and deploy this type of server.

Connect with OAuth

Choose OAuth 2.1 (per-user) for third-party MCP servers that require a user login, such as Notion, Linear, or Atlassian. Enter only the URL; Scopes, Client ID, and Client secret are optional.

1. Save the server. Its page opens in a new tab.
2. In the Connection section, select Connect your account next to Your connection. MINEO discovers the provider's authorization server automatically, registers itself as a client when the provider supports dynamic client registration, and opens the provider's consent screen in a popup. Allow popups for MINEO.
3. Approve the access. As soon as the popup finishes, the row shows Connected as account and MINEO indexes the server's tools with your credentials, reporting how many it found.

Connections are personal. Every user who chats with an Assistant linked to the server connects once, either from the server page or from the Connect banner shown at the top of the thread. Users who have not connected keep using the Assistant: the server's tools are skipped and the reasoning chain reports that the server could not be reached.

Disconnect removes only your own credentials; you can reconnect at any time. All the MCP servers you have authorized are also listed in My profile → Connected accounts, next to your personal accounts, where you can disconnect any of them; the Your connections link on the server page takes you there.

MINEO refreshes tokens before they expire and retries once after a 401. If the provider does not issue refresh tokens, reconnect when the access token expires.

Providers without dynamic client registration

If the provider does not support dynamic client registration, create an OAuth client in the provider yourself with the redirect URI https://<your MINEO domain>/api/mcp/oauth/callback/, then enter its Client ID and Client secret in the server form. Leave Scopes empty to request the scopes the server declares (or openid as a minimum); set them by hand only when the provider needs specific ones.

warning

Only connect MCP servers from developers you trust. Review the exposed tools, use the least-privileged authentication available, and require confirmation for sensitive operations.

Build your own MCP server

You can use FastMCP to expose custom Python tools, resources, and prompts. See the Model Context Protocol guide to connect to remote MCP servers for protocol details and security guidance.