MCP Server Integration

The Sellfern MCP integration lets MCP-compatible AI tools work with Sellfern through safe, server-side API calls. Use this page as a V1-safe setup guide for agents that need to read or update Sellfern data.

The API Reference is the source of truth for public endpoint availability. If a tool or workflow needs an endpoint that is not listed there, treat that capability as unavailable for public integrations until Sellfern documents it.

Prerequisites

Node.js 18 or later on the machine running the MCP server
A Sellfern API key with the minimum scopes required by the tools you enable
Claude Desktop, Cursor, OpenCode, or another MCP-compatible client

Configure authentication

Store your Sellfern API key in the MCP server environment and send it to Sellfern with the x-api-key header from server-side code.

{
  "mcpServers": {
    "sellfern": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"],
      "env": {
        "SELLFERN_API_URL": "https://api.sellfern.com",
        "SELLFERN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Never place API keys in client-side JavaScript, shared prompts, logs, or repository files.

Build and run

From the MCP server project directory, install dependencies and build the server.

npm install
npm run build

Then point your MCP-compatible client at the compiled server entry point and restart the client so it can discover the Sellfern tools.

Tool availability

Only expose MCP tools backed by endpoints present in the V1 API Reference. Capabilities from older examples, internal deployments, or live demos may be deferred for public V1. Before enabling a tool:

Confirm the underlying endpoint appears in /api-reference.
Confirm the API key has the minimum required scope.
For write tools, send an Idempotency-Key header and reuse the same key when retrying the same logical mutation after a timeout or uncertain server error.
Return clear errors to the agent when Sellfern responds with 403 missing_scope, 404 not_found, or 422 idempotency_conflict.

Organization isolation

API keys are scoped to one organization. If a tool receives 404 not_found, do not tell the user that the resource exists in another organization. Ask the user to confirm they selected the correct organization and API key.

Troubleshooting

The MCP client cannot find the server

Verify that the args path points to the built server entry point and that the file exists before restarting the client.

Sellfern returns `401 unauthorized`

Check that the API key is present in the MCP server environment and that the server sends it with the x-api-key header.

Sellfern returns `403 missing_scope`

Request a new API key with only the minimum additional scope required for the tool the user is trying to run.

Developer Guides

Integrations

Prerequisites

Configure authentication

Build and run

Tool availability

Organization isolation

Troubleshooting

The MCP client cannot find the server

Sellfern returns `401 unauthorized`

Sellfern returns `403 missing_scope`

​Prerequisites

​Configure authentication

​Build and run

​Tool availability

​Organization isolation

​Troubleshooting

​The MCP client cannot find the server

​Sellfern returns 401 unauthorized

​Sellfern returns 403 missing_scope

Prerequisites

Configure authentication

Build and run

Tool availability

Organization isolation

Troubleshooting

The MCP client cannot find the server

Sellfern returns `401 unauthorized`

Sellfern returns `403 missing_scope`