Skip to main content
A Custom MCP Server turns your own API into a set of MCP tools that agents can use. You create one as part of a custom connection: the connection holds the credentials, and the MCP server exposes the API’s operations as tools that call it using those credentials.

​
How it’s created

Custom MCP servers are set up from a custom connection, not on their own. In the web app, start a custom connection under Tools → Connections, then complete the three-step editor:
1

Basic Info & Auth Type

Name the integration, optionally upload an icon, and choose how it authenticates: OAuth 2.0 (Authorization Code or Client Credentials), API Key, or Basic Auth.
2

Auth Configuration

Enter the auth details for the type you chose — for OAuth, the authorize/token URLs, client ID and secret, and scopes; for API Key or Basic Auth, the API base URL and a test endpoint. Pinkfish uses this to obtain and store credentials for the connection.
3

MCP Server Setup

Create the MCP server for this connection. Either map it to an existing MCP server, or generate a new one from an OpenAPI spec — upload the spec and Pinkfish turns its operations into tools. The server is bound to the connection, so its tools call your API with the connection’s credentials.
When you finish, the server appears under Tools → Custom MCP Servers, bound to your connection.
Custom MCP Servers are scoped to one organization — the one you’re in when you create them. They can only be used by agents and API credentials in that same organization. See Authentication for organization scoping.

​
Find the server ID

Open the server under Tools → Custom MCP Servers. The id — a short token such as d7r2dt3l9foc7192703g, not the display name — is what you use to attach it via the API.

​
Attach it to an agent

Custom MCP servers attach through the same servers field as built-in servers, using the agent-management tools. Reference the server by its id: 
curl -s -X POST "https://mcp.app.pinkfish.ai/agent-management" \
  -H "Authorization: Bearer $PINKFISH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "agent-management_agent_update",
      "arguments": {
        "agentId": "ua_abc123",
        "servers": [
          { "name": "d7r2dt3l9foc7192703g", "allTools": true }
        ]
      }
    },
    "id": 1
  }'
This works the same on agent_create. Use { "name": "<id>", "tools": { "tool_name": {} } } to attach specific tools instead of all of them. When the agent runs, it calls the server’s tools using the connection’s stored credentials.
agent_create / agent_update validate servers[].name against your organization’s catalog. A Custom MCP Server is accepted only when:
  • it is referenced by its id (not its display name),
  • it has at least one tool, and
  • it lives in the same organization as the API key behind your token.
If the name isn’t recognized, the error lists the valid server names and ids — use the exact id shown there.