Custom MCP Servers

Turn your own API into an MCP server through a custom connection

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.

Two kinds of custom server

The term covers two things that behave differently at call time, and the difference matters if you want per-request headers:

Kind	How it’s created	Runs where
Generated	From an OpenAPI spec on Step 3 above	Pinkfish calls your API directly, per the spec
Remote	Registered against a URL you operate that already speaks MCP	Pinkfish proxies MCP requests to your server

Only remote servers receive forwarded request headers. If you need per-user identity at your own server, you need a remote server — a generated one will not receive them. Contact [e-mail] to register a remote server.

Per-request header passthrough

A remote MCP server can receive per-request headers from the caller, which is how you authenticate or authorize at the level of an individual end user rather than per connection.

Send any header prefixed X-Pf-Forward- on the invoking request. Your server receives it with the prefix stripped and the name lowercased:

X-Pf-Forward-User-Id: u123    →    user-id: u123

This works from both the Agent API channel and agent_invoke. The prefix is the allowlist: headers without it — including Authorization and every Pinkfish-internal header — are never forwarded. Full rules, reserved names, and the case-sensitivity caveat are documented on the Agent API channel page.

The credential your server receives in Authorization is the one stored on the connection backing the server. Forwarded headers are additional, and cannot override it.

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.