# MCP Server

## Overview

The Scaleflex MCP Server enables AI agents and Large Language Models (LLMs) to securely interact with the [**Scaleflex API**](https://developers.scaleflex.com/) through a curated set of tools. It allows LLMs to retrieve and interact with assets from your Scaleflex project.

The server implements the [**Model Context Protocol (MCP)**](https://modelcontextprotocol.io/) and is designed to be consumed by MCP-compatible clients such as [Claude Desktop](https://claude.com), [Mistral Le Chat](https://chat.mistral.ai/), [goose](https://block.github.io/), [LibreChat](https://www.librechat.ai/), etc.

## Architecture

* **Protocol**: [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
* **Transport**: Streamable HTTP
* **Authentication**: OAuth2 or API token (Bearer)
* **Upstream API**: [Scaleflex DAM API](https://developers.scaleflex.com/)

The server does not expose the full upstream API surface. Instead, it relies on a **simplified and validated OpenAPI specification** to ensure compatibility with MCP tooling and LLM function-calling mechanisms.

## Public MCP Endpoint

```
https://mcp.scaleflex.com/mcp
```

## Authentication

The Scaleflex MCP Server supports two authentication mechanisms:

### OAuth2

If supported by the MCP client, OAuth2 is the recommended authentication method. The client handles token acquisition and renewal automatically.

### API Token Authentication

Clients may also authenticate by explicitly passing an `Authorization` header:

```
Authorization: Bearer TOKEN:KEY
```

Where:

* `TOKEN` is your Scaleflex project token.
* `KEY` is an API key associated with the project.

## Client Setup Guides

### Claude Desktop

#### Custom Connector (Remote MCP)

Follow Anthropic’s official guide for [**Custom Connectors Using Remote MCP**](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp). This option is available for Pro, Max, Team and Enterprise plans.

#### Local Proxy Connector

If custom connectors are unavailable, a local MCP proxy can be used via the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) package:

```json
{
  "mcpServers": {
    "scaleflex-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.scaleflex.com/mcp",
        "--allow-http",
        "--header",
        "Authorization:${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "Bearer TOKEN:KEY"
      }
    }
  }
}
```

***

### Mistral Le Chat

1. Navigate to **Intelligence → Connectors**
2. Click **Add Connector**
3. Select **Custom MCP Connector**
4. Set the MCP URL to `https://mcp.scaleflex.com/mcp`
5. Choose authentication:
   * OAuth2, or
   * API Token (Bearer `TOKEN:KEY`)
6. Activate the connector in chat

***

### Goose

Configure Goose to load the MCP server as an extension.

#### OAuth2 configuration:

```yaml
extensions:
  scaleflex:
    enabled: true
    type: streamable_http
    name: scaleflex
    uri: https://mcp.scaleflex.com/mcp
    headers: {}
    description: Enables interaction with the Scaleflex API
    timeout: 300
```

#### API token configuration:

```yaml
extensions:
  scaleflex:
    enabled: true
    type: streamable_http
    name: scaleflex
    uri: https://mcp.scaleflex.com/mcp
    headers:
      authorization: bearer TOKEN:KEY
    description: Enables interaction with the Scaleflex API
    timeout: 300
```

Enable the extension so that its tools are available to the LLM during conversations.

***

### LibreChat

1. Deploy LibreChat following the official Quick Start guide
2. Add the MCP server to `librechat.yaml`:

```yaml
mcpServers:
  scaleflex:
    type: streamable-http
    initTimeout: 500000
    url: https://mcp.scaleflex.com/mcp
```

3. Restart the LibreChat API service
4. Authenticate via OAuth2 when enabling the MCP server in chat

## Available Tools

| Tool Name          | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `fileList`         | Search and retrieve files with metadata, filters, and AI-assisted search |
| `folderList`       | List and search folders with ownership and size information              |
| `productList`      | Retrieve all available products                                          |
| `productFiles`     | List files attached to a specific product reference                      |
| `tagList`          | Retrieve all available tags                                              |
| `labelList`        | Retrieve all available labels and usage metadata                         |
| `metaList`         | Retrieve the full custom metadata taxonomy                               |
| `metaGetOptions`   | Retrieve selectable options for a metadata field                         |
| `get_headers`      | Return HTTP headers received by the MCP server                           |
| `get_token`        | Return the authenticated project token                                   |
| `get_current_time` | Return the current UTC time (ISO 8601)                                   |

## Troubleshooting

### Authentication Errors (401 / 403)

* Verify the token and API key are valid
* Ensure the `Authorization` header format is correct
* Confirm the client supports the chosen authentication method

### Tools Not Appearing in the LLM

* Ensure the MCP server is enabled in the client UI
* Confirm the MCP endpoint is publicly reachable
* Restart the client after configuration changes

### Timeout or Connection Errors

* Increase client-side timeout values
* Verify outbound HTTPS access from the client environment
* Check for corporate firewall or proxy restrictions

### Unexpected Tool Arguments or Validation Errors

* Ensure the LLM is not generating unsupported fields
* Retry with simpler, more explicit prompts
* [Contact us](https://www.scaleflex.com/contact-us) for additional help

## Changelog

### v0.1.0 - Public release

* Initial MCP server implementation
* OAuth2 and API token authentication
* Compatibility with major MCP-enabled clients