> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

When you finish, the server appears under **Tools → Custom MCP Servers**, bound to your connection.

<Note>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](/api-reference/platform/authentication) for organization scoping.</Note>

## 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](/api-reference/platform/agent-management) tools. Reference the server by its **id**:

```bash theme={null}
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 [support@pinkfish.ai](mailto:support@pinkfish.ai) 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](/api-reference/platform/agent-api-channel#forwarding-headers-to-your-mcp-server) 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](/api-reference/platform/agent-api-channel#forwarding-headers-to-your-mcp-server) page.

<Note>
  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.
</Note>

<Warning>
  `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.
</Warning>