Custom MCP Servers

In addition to the pre-built integrations, you can connect your agents to any service that exposes an MCP (Model Context Protocol) compatible endpoint. This is useful for integrating with internal tools, proprietary systems, or third-party services that do not have a pre-built template.

When to Use Custom MCP Servers

Custom MCP servers are a good fit when:

• You have an internal tool or service that you want your agents to interact with.
• You are using a third-party service that is not available as a pre-built template.
• You have built your own MCP server to expose specific capabilities.
• You want to connect to an open-source MCP server from the community.

Requirements

Custom MCP servers must meet the following requirements:

• HTTPS endpoint — The server must be accessible over HTTPS.
• MCP-compatible — The server must implement the Model Context Protocol specification.
• Remote/URL-based — Only URL-based MCP servers are supported. Local or stdio-based servers cannot be connected directly.

Setting Up a Custom MCP Server

Step 1: Create the Connection

1. Navigate to Organization > Connectors in Devs.ai.
2. Click Create Custom.
3. Fill in the connection details:

Field	Description
Server Name	A display name to identify the connection (for example, "Internal CRM")
Server URL	The HTTPS endpoint of your MCP server
Logo	(Optional) Upload an image to help identify the connector

Step 2: Configure Authentication

Choose the authentication method that matches your MCP server's requirements:

No Authentication

Select None if your server does not require credentials. This is suitable for servers on a private network or behind a VPN.

API Key

1. Select API Key.
2. Enter the API key value.
3. The key is encrypted and stored securely.

The platform sends the API key in the Authorization header as a Bearer token when calling your MCP server.

OAuth

1. Select OAuth.
2. Enter the Client ID and Client Secret for your OAuth provider.
3. Configure the authorization URL, token URL, and scopes as required by your service.

Pass-Through Headers

1. Select Pass-Through Headers.
2. Configure which headers from the user's request should be forwarded to your MCP server.

This is ideal for internal services that accept the same authentication tokens your users already send to Devs.ai. For details, see Pass-Through Headers Authentication.

Step 3: Discover and Select Tools

After saving the connection, the platform connects to your MCP server and discovers the available tools. Each tool represents a capability your server exposes (for example, "search records", "create order", or "get report").

1. Review the list of discovered tools.
2. Select the tools you want to make available to agents.
3. Click Save.

📝 Note: If your MCP server is not reachable at the time of setup, tool discovery will fail. Make sure the server is running and accessible before configuring it.

Connecting to Agents

Once a custom MCP server is configured at the organization level, agent creators can connect it to their agents the same way as pre-built integrations:

1. Open your agent's Tools configuration.
2. Under MCP Server, select your custom connector.
3. Choose which tools the agent should have access to.
4. Save the agent configuration.

Building Your Own MCP Server

If you want to build a custom MCP server, it needs to implement the MCP specification. Here are some key points:

• The server must respond to JSON-RPC requests over HTTP.
• It should implement the tools/list method to expose available tools.
• Each tool should have a clear name, description, and input schema.
• The server should handle authentication as appropriate for your use case.

For guidance on building MCP servers, refer to the Model Context Protocol specification and the MCP SDK documentation.

Limitations

• Up to 100 tools per MCP server connection.
• HTTPS required — HTTP endpoints are not supported.
• URL-based only — stdio and local subprocess MCP servers are not supported.
• Timeout — Requests to custom MCP servers may time out if the server takes too long to respond.

Troubleshooting

Problem	Possible Cause	Solution
Tool discovery fails	Server is unreachable	Verify the server URL is correct and the server is running. Check that it is accessible over HTTPS.
Authentication errors	Wrong credentials	Double-check the API key, Client ID/Secret, or header values.
Tools not appearing in agent	Connector not enabled in chat	Go to Connectors and make sure Enable in Chat is turned on.
Agent cannot call tools	Tools not selected	Check that the desired tools are selected in both the connector settings and the agent configuration.
Slow responses	MCP server latency	Check the performance of your MCP server. Consider optimizing or increasing its resources.