Using the Stellarbridge MCP

Goal: Install and use the Stellarbridge MCP server so an AI coding agent (Cursor, Claude, and others) can work with your Drive, transfers, file requests, projects, and audit logs from the conversation.

The Stellarbridge MCP server exposes the Stellarbridge API as Model Context Protocol (MCP) tools. Once the server is installed and configured in your agent, you can ask the agent in plain language to list files, upload or download objects, create file requests, manage projects, or query audit logs. The agent selects and calls the right tools for you.

The MCP can be downloaded from the official repository: github.com/EpykLab/stllr-mcp.

What the server provides

The server exposes five tool groups (namespaces). Each group maps to a part of the Stellarbridge API:

Namespace	Tool count	What you can do
drive	14	List, create, rename, move, delete files and folders; get upload/download URLs; share objects; manage policy attachments
transfers	10	List, get, delete, share transfers; add transfers to Drive; initialize and finalize multipart uploads
requests	3	Create, inspect, and delete file upload requests sent to external recipients
projects	3	List, create, and delete Drive projects
audit	3	Query audit logs by time range, actor, file name, or file hash

You do not call these tools by name yourself; you describe what you want (e.g. “List all files in my Compliance project”) and the agent invokes the appropriate tools.

Prerequisites

Python 3.13 or later (to run the server).
Install method: uv (recommended) or pip.
An agent identity for the MCP. Create an agent identity in the dashboard; it provides an API key that the server uses (or exchanges for a JWT) on each request. New agent identities automatically receive the Agent RBAC role so they can call the required API routes; object-level access (which projects and files the agent can use) is controlled by policies you attach to the identity.

Installation

Install from the stllr-mcp repository:

With uv (recommended)

uv tool install git+https://github.com/EpykLab/stllr-mcp

This installs the stellarbridge-mcp binary into uv’s tool environment and adds it to your PATH.

With pip

pip install git+https://github.com/EpykLab/stllr-mcp

Verify

stellarbridge-mcp --help

If the command is not found, ensure the directory where uv or pip installs binaries is on your PATH. With uv, run uv tool dir --bin and add that directory to your shell profile.

Configuration

The server uses environment variables only (no config file). Every variable is prefixed with STELLARBRIDGE_:

Variable	Required	Default	Description
`STELLARBRIDGE_API_KEY`	Yes*	—	API key from your agent identity; exchanged for a JWT on first request
`STELLARBRIDGE_JWT_TOKEN`	Yes*	—	Pre-supplied JWT; skips key exchange (use one of API_KEY or JWT_TOKEN)
`STELLARBRIDGE_API_URL`	No	`http://localhost:8080`	Base URL of your Stellarbridge API
`STELLARBRIDGE_HTTP_TIMEOUT`	No	`30`	HTTP request timeout in seconds

*Provide either STELLARBRIDGE_API_KEY or STELLARBRIDGE_JWT_TOKEN, not both.

Cloud Stellarbridge: set STELLARBRIDGE_API_URL to https://api.stellarbridge.app (or your tenant URL).
Self-hosted: set it to your instance base URL (e.g. https://files.yourcompany.com).

Installing the server into your agent

You must register the MCP server in your AI agent’s configuration so the agent can start the process and call the tools. Below are steps for common clients.

Cursor

Open Cursor → Settings → MCP (or edit ~/.cursor/mcp.json).
Add a server entry for stellarbridge-mcp and the required environment variables:

{
  "mcpServers": {
    "stellarbridge": {
      "command": "stellarbridge-mcp",
      "env": {
        "STELLARBRIDGE_API_KEY": "your_api_key",
        "STELLARBRIDGE_API_URL": "https://api.stellarbridge.app"
      }
    }
  }
}

Reload MCP settings. The stellarbridge-* tools appear in Composer and can be used by the agent.

Claude Code (Claude Code)

Add the server with the CLI:

claude mcp add stellarbridge \
  -e STELLARBRIDGE_API_KEY=your_api_key \
  -e STELLARBRIDGE_API_URL=https://api.stellarbridge.app \
  -- stellarbridge-mcp

Or add it manually to ~/.claude/mcp.json (or a project-local .claude/mcp.json):

{
  "mcpServers": {
    "stellarbridge": {
      "command": "stellarbridge-mcp",
      "env": {
        "STELLARBRIDGE_API_KEY": "your_api_key",
        "STELLARBRIDGE_API_URL": "https://api.stellarbridge.app"
      }
    }
  }
}

Restart Claude Code or run /mcp to confirm the server is connected.

Claude Desktop

Open Claude → Settings → Developer → Edit Config.
Add the stellarbridge entry under mcpServers as in the Cursor example above (same JSON shape).
Save and restart Claude Desktop. Stellarbridge tools show up in the tool picker.

OpenCode

Edit ~/.config/opencode/config.json and add:

{
  "mcp": {
    "servers": {
      "stellarbridge": {
        "command": "stellarbridge-mcp",
        "env": {
          "STELLARBRIDGE_API_KEY": "your_api_key",
          "STELLARBRIDGE_API_URL": "https://api.stellarbridge.app"
        }
      }
    }
  }
}

Restart OpenCode; the tools are available in sessions.

Goose

Add a toolset in ~/.config/goose/config.yaml:

extensions:
  stellarbridge:
    type: stdio
    cmd: stellarbridge-mcp
    env:
      STELLARBRIDGE_API_KEY: your_api_key
      STELLARBRIDGE_API_URL: https://api.stellarbridge.app

Enable it for a session:

goose session --with-extension stellarbridge

Or set it as a default extension so it loads in every session.

Other MCP clients (stdio)

The server uses standard MCP over stdio. Run the binary and connect your client to its stdin/stdout:

STELLARBRIDGE_API_KEY=your_api_key \
STELLARBRIDGE_API_URL=https://api.stellarbridge.app \
stellarbridge-mcp

For clients that support SSE transport, you can run with --transport sse --port 8081 or set FASTMCP_TRANSPORT=sse and FASTMCP_PORT=8081 in the environment.

Using the tools

After the server is installed and configured, use natural language in your agent. The agent will choose and call the right Stellarbridge tools.

Example prompts:

“List all files in my Compliance project”
“Upload report.pdf to the Legal folder in the Compliance project”
“Send a file request to contractor@example.com for this quarter’s invoice”
“Show me audit logs for the last 24 hours for user alice@example.com”
“Create a new project called M&A Diligence and share NDA.pdf with partner@example.com”

The same permissions and policies that apply in the dashboard apply to tool calls. Your agent identity has the Agent RBAC role (assigned when the identity was created), which allows it to call the Drive and object API routes. Which projects and files the agent can access is controlled by policies attached to that identity; attach policies in the dashboard to scope what the MCP can do.

Upgrading

# With uv
uv tool upgrade stellarbridge-mcp

# With pip
pip install --upgrade git+https://github.com/EpykLab/stllr-mcp

Restart your agent or MCP client after upgrading so it uses the new binary.

Troubleshooting

`stellarbridge-mcp` not found after install

The binary may not be on your PATH. For uv, run uv tool dir --bin and add that directory to your shell profile (e.g. export PATH="$(uv tool dir --bin):$PATH").

401 Unauthorized

The API key may be invalid, expired, or revoked, or the agent identity may have been deleted. New agent identities automatically receive the Agent RBAC role, so route access is granted at creation. If you see 401, create a new agent identity in the dashboard (it will provide a new API key and the Agent role) and set STELLARBRIDGE_API_KEY (or STELLARBRIDGE_JWT_TOKEN) in your agent’s MCP config.

Wrong API or empty results

For cloud Stellarbridge use STELLARBRIDGE_API_URL=https://api.stellarbridge.app. For self-hosted, use your instance’s base URL. Wrong URL often leads to connection errors or empty lists.

Tool calls time out

Increase STELLARBRIDGE_HTTP_TIMEOUT (default 30 seconds). Large uploads or slow networks may need a higher value (e.g. 60 or 120).

Agent does not see the tools

Confirm the MCP server is listed as connected in your agent (e.g. Cursor MCP panel, Claude’s /mcp). Restart the agent after changing the config. Ensure the command is exactly stellarbridge-mcp and that the env vars are set in the same config object as the server.

How agent access works

Access for the MCP (and any client using an agent identity API key) has two layers:

RBAC (route-level). The identity must have permission to call the API route (path and method). When you create an agent identity in the dashboard, it is automatically assigned the Agent role. That role allows the identity to call the Drive and object APIs (list folders, upload, download, list projects, etc.). Without this role, the API would reject the request before any handler runs.
Object-level (policies). Which projects, folders, and files the agent can actually access is determined by policies attached to the identity. Policy attachments alone do not grant the right to call routes; they only control what the agent can do once route access is allowed. Attach policies to the agent identity in the dashboard (e.g. via the identity’s policy attachments) to scope which objects the MCP can list, read, or modify.

So: the Agent role lets the agent call the routes; policies on the identity define what it can see and do on those routes. See RBAC and Writing policies for details.