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

# MCP Server Integration

> Connect MCP-compatible AI tools to Sellfern using public V1 APIs and scoped API keys.

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.

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

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

```json theme={null}
{
  "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.

```bash theme={null}
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:

1. Confirm the underlying endpoint appears in `/api-reference`.
2. Confirm the API key has the minimum required scope.
3. 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.
4. 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.