Skip to main content
Custom integrations let an organization connect a remote Model Context Protocol (MCP) server that is not already available in Odella’s integration catalog. Odella discovers the server’s tools and makes the approved integration available for assignment to workers.
A custom MCP server is an external service selected by your organization. Only connect a server whose operator, security practices, data handling, and tools your organization has reviewed and approved.

​
Requirements

A typical endpoint looks like:
Do not put an API key in the URL. Enter it in the authentication field instead.

​
Add a custom integration

1

Open Integrations

Go to Integrations and select Custom Integration. The button is available only to account administrators.
2

Name the integration

Enter a name that identifies the service and its purpose. This name appears when administrators and workers browse connected tools.
3

Enter the MCP server URL

Provide the full HTTPS streamable HTTP endpoint. Do not enter a website home page unless it is also the MCP endpoint.
4

Test the connection

Select Test. Odella checks the endpoint, detects the supported authentication method, and validates the tool catalog before the integration can be created.
5

Complete authentication

If the server uses an API key, enter the key and retest. If Odella detects OAuth 2.1, continue to the provider’s authorization flow.
6

Review discovered tools

Confirm that every exposed tool is expected and appropriate for your organization. Do not continue if the server exposes unexpected write, send, administrative, or destructive capabilities.
7

Create the integration

Select Create integration. A validated test can be used for up to 10 minutes and only by the administrator and account that started it. If it expires or the configuration changes, test the server again.

​
Authentication options

Use this only for an approved endpoint that intentionally accepts requests without credentials. Public reachability does not mean a server is safe or appropriate to connect.
Odella attempts to discover a suitable logo from the endpoint. If none is available, you can provide a direct HTTPS URL to a PNG, JPEG, GIF, or WebP image. The logo is presentation metadata only. It does not establish the identity or trustworthiness of the server.

​
Assign the integration to a worker

Creating a custom integration does not grant every worker access.
  1. Open the intended worker.
  2. Open Tools in the skill tree.
  3. Find the custom integration and assign it.
  4. Review the worker’s Tool approval policy.
  5. Test each required tool with non-sensitive data before production use.
Custom integration access is account-scoped and worker assignment is enforced separately. A worker without an explicit assignment cannot use that custom integration.

​
Security behavior

Odella applies a conservative trust model to custom MCP tools:
  • The remote server and its returned content are treated as untrusted external input.
  • A successful connection test validates protocol compatibility and catalog safety; it does not certify the server or its operator.
  • Custom tools are handled conservatively for approval purposes, including tools that the server describes as read-only.
  • Worker-level allow and block rules still apply.
  • API keys and OAuth credentials are stored as protected integration credentials and used by the platform rather than disclosed to the worker.
  • Requests are subject to platform safety, availability, and resource controls.
  • Setup, refresh, enablement, and deletion activity is recorded for operational and security review.
Information sent to a custom tool is disclosed to the external MCP server. The server operator’s terms, privacy notice, retention, hosting locations, and subprocessors may apply to that information.

​
Current limits

Catalogs, requests, and concurrent operations are also subject to platform safety and availability controls. Contact Odella if your approved use case requires a different supported configuration.

​
Manage a custom integration

Select the settings button beside a custom integration to open its management view. A failed catalog refresh does not replace the last successfully validated catalog. The integration may be marked unavailable or require reconnection until an administrator resolves the failure.

​
Connection states

​
Troubleshooting

Confirm that the endpoint is publicly reachable, begins with https://, uses the standard HTTPS port, and does not contain a username, password, query string, or fragment. Localhost, private-address, internal-network, and metadata-service destinations are rejected.
Confirm that the remote service is available and responds promptly to MCP initialization and tool discovery. Then retest.
Enter the key, choose Authorization: Bearer or X-API-Key, and retest. Confirm the server expects the selected header format.
Open the integration settings and select Authorize or Reconnect. Complete the provider consent flow using the intended account.
Confirm that the URL is the MCP endpoint and that the server supports MCP tool discovery. Odella cannot create a non-OAuth integration with an empty tool catalog.
Review the remote server’s tool names and schemas. The server must return a valid catalog within platform safety limits.
Open the integration settings and select Refresh. Review the updated tool list and retest the worker’s approval rules.

​
Review checklist

Before approving production use, record:
  • The service owner and business purpose
  • The MCP server operator and endpoint
  • Authentication method and credential owner
  • Data categories that may be sent to the server
  • Hosting region, retention, subprocessors, and deletion terms
  • Expected tools and permitted operations
  • Workers allowed to use the integration
  • Tool approval and human review requirements
  • Revocation and incident-response contacts
For questions about an Odella control, contact support@odella.ai. Questions about the external server should be directed to its operator.