Skip to content
Skills Library
AI & agents · Tool integration

voxel51-agent-setup

/voxel51-agent-setup

Connect a local AI agent (Claude Code, Cursor, or any MCP client) directly to a Voxel51 deployment over MCP, authenticating as yourself with your own account permissions. Use when a user wants to link their coding agent to a Voxel51 deployment, run FiftyOne operators from outside the App, or asks about remote/MCP access to a Voxel51 deployment.

Licence
Apache-2.0
Last repository change
29.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
7
Deprecation

No signals detected. Repository changed on 29.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Connect a local AI agent (Claude Code, Cursor, or any MCP client) directly to a Voxel51 deployment over MCP, authenticating as yourself with your own account permissions. Use when a user wants to link their coding agent to a Voxel51 deployment, run FiftyOne operators from outside the App, or asks about remote/MCP access to a Voxel51 deployment.

Original author description

Connect a local AI agent (Claude Code, Cursor, or any MCP client) directly to a Voxel51 deployment over MCP, authenticating as yourself with your own account permissions. Use when a user wants to link their coding agent to a Voxel51 deployment, run FiftyOne operators from outside the App, or asks about remote/MCP access to a Voxel51 deployment.

How it works

  1. Voxel51 Notice
  2. Key Directives
  3. Prerequisites
  4. Workflow
  5. Using the tools well
  6. Generating Deeplinks
  7. Troubleshooting
  8. Resources
Original SKILL.md headings · 194 lines, 1,614 words
SKILL.md preview
---
name: voxel51-agent-setup
description: Connect a local AI agent (Claude Code, Cursor, or any MCP client) directly to a Voxel51 deployment over MCP, authenticating as yourself with your own account permissions. Use when a user wants to link their coding agent to a Voxel51 deployment, run FiftyOne operators from outside the App, or asks about remote/MCP access to a Voxel51 deployment.
---

# Set Up an Agent for Voxel51

Pair a local agent (Claude Code, Cursor, any MCP-compliant client) to a Voxel51
deployment over MCP. Once paired, the agent acts as the approving user, with
exactly that user's own role and dataset permissions, no separate service
account or shared credential involved.

## Voxel51 Notice

This is a **Voxel51** feature. Before proceeding, inform the user:

> **Note:** Remote agent access is a Voxel51-only capability, and it must
> be explicitly enabled by the deployment's administrator (it ships behind a feature
> flag, off by default). If you're using the open-source version of FiftyOne, or a
> Voxel51 deployment where this hasn't been turned on yet, this won't work. For a
> **self-hosted (on-premise)** deployment, this must first be enabled by your
> Voxel51 Customer Success contact, reach out to them to turn it on.
>
> Would you like to proceed?

Wait for confirmation. If the user is on OSS, point them at the local `fiftyone-mcp`
server instead (already installed alongside this skill collection), which works
against a local FiftyOne install without any of the steps below.

## Key Directives

**ALWAYS follow these rules:**

1. **Confirm Voxel51 + the feature flag first.** Don't attempt any of the steps
   below until the user confirms both that they're on a Voxel51 deployment and
   that remote agent access is enabled for it. If they're not sure, tell them to ask
   their FiftyOne admin.
2. **Always use the user's own deployment URLs.** Never invent, assume, or reuse a
   URL from an example, docs page, or a different deployment. Ask for them if not
   given.
3. **Never ask the user to paste, type, or store an access token by hand.** The
   MCP connection flow below handles credential storage automatically and safely.
   If you find yourself about to ask for a raw key or token, stop, that's the
   wrong step.
4. **A one-time browser approval is required and cannot be skipped.** An MCP
   client's OAuth connection needs a human to sign in and click Approve in a
   browser. Tell the user to expect this, then wait for it, don't suggest a way
   around it.
5. **Treat a permission refusal as expected behavior, not a bug.** If an operator is
   missing from the list, or a pairing attempt is refused because the approving user
   lacks a specific permission, that's the live permission check working correctly,
   see Troubleshooting. Never suggest disabling, bypassing, or "working around" a
   refusal.
6. **New MCP servers only attach on the next session.** After adding one, tell the
   user plainly they need to restart their agent (or start a fresh conversation)
   before the tools are usable; it will not work in the current turn.
7. **Consult `references/` before guessing at an operator or its arguments.** Don't
   invent an operator URI or parameter shape from general FiftyOne knowledge or a
   past conversation — different deployments have different plugins installed and
   different schemas. Read the matching category file under `references/` first,
   then confirm the exact current arguments with `get_operator_schema` before
   calling `execute_operator`. See "Using the tools well" below.

## Prerequisites

- A Voxel51 deployment with remote agent access enabled by an admin. On a
  **self-hosted** deployment, this must first be enabled by the user's Voxel51
  Customer Success contact, not just a flag their own admin can flip; tell them
  to reach out to Customer Success if it isn't on yet.
- The deployment's gateway URL. On **Voxel51 Cloud**, the host is always
  `app.voxel51.com`, no need to ask. On a **self-hosted** deployment, ask the
  user or their FiftyOne admin for the hostname, don't guess it. Either way
  the path suffix is fixed: `https://<host>/api/proxy/fiftyone-teams/mcp`.
- An MCP client that supports remote HTTP servers with OAuth (Claude Code,
  Cursor, and similar all do).

## Workflow

1. Ask which they're on: Voxel51 Cloud (host is `app.voxel51.com`) or
   self-hosted (ask for their deployment's hostname). The gateway URL is
   `https://<host>/api/proxy/fiftyone-teams/mcp`.
2. Add it as a remote MCP server. In Claude Code:
   ```
   claude mcp add --transport http --scope user voxel51-agent-gateway \
     https://<your-deployment>/api/proxy/fiftyone-teams/mcp \
     --client-id voxel51-agent-mcp
   ```
   The `--client-id` is required: this deployment's auth server doesn't support
   Dynamic Client Registration, so a client that tries to register one on its own
   fails with `Incompatible auth server: does not support dynamic client
   registration`. `voxel51-agent-mcp` is the fixed client id every agent uses.
   Only run this after the user confirms; it edits their global agent config. For
   other clients, give the equivalent config snippet, e.g. Claude Desktop / Cursor:
   ```json
   {
     "mcpServers": {
       "voxel51-agent-gateway": {
         "type": "http",
         "url": "https://<your-deployment>/api/proxy/fiftyone-teams/mcp"
       }
     }
   }
   ```
   If the client's config format has no explicit way to pin a client id and it
   fails the same DCR error above, that client isn't yet supported for this path.
3. Tell the user to restart their agent (per Key Directive 6), then trigger the
   connection (e.g. by trying to use one of the new tools). Their agent will open a
   browser for a one-time OAuth consent screen, they sign in and approve, and the
   connection is complete, no API key needed.
4. Once connected, five tools are available: `list_operators`, `get_operator_schema`,
   `execute_operator`, `list_delegated_operations`, `get_delegated_operation` — covering
   whatever FiftyOne operators the approving user's account is permitted to see and run,
   live-checked on every call. Long-running operators can be run in the background with
   `execute_operator(..., delegate=True)`; check the result's `delegated` field (not every
   operator supports it) and poll `get_delegated_operation` for the outcome.

## Using the tools well

The five MCP tools (`list_operators`, `get_operator_schema`, `execute_operator`,
`list_delegated_operations`, `get_delegated_operation`) are generic — they reach
whatever FiftyOne operator you name. The operator catalog behind them is large
(typically hundreds, varying by deployment and the
connected user's own permissions), and most individual operators carry no written
description of their own. Don't call `list_operators` cold and scan every name, and
don't guess at an operator's purpose or arguments from memory.

Instead:

1. **Start from `references/`, not from `list_operators`.** Read the one file that
   matches the current task:
   - [`references/datasets-and-samples.md`](references/datasets-and-samples.md) —
     dataset lifecycle, views, fields/schema, sample and label edits, indexes,
     media import, workspaces.
   - [`references/analysis-and-labeling.md`](references/analysis-and-labeling.md) —
     brain methods, embeddings, model evaluation, data quality, auto-labeling,
     agentic labeling, annotation, zoo models, workflows, label schemas.
   - [`references/delegated-operations.md`](references/delegated-operations.md) —
     running things in the background, checking on them, delegated-run metadata.
   - [`references/agent-tools.md`](references/agent-tools.md) — the FiftyOne Agent's
     own operators (conversations, code execution, plugin/skill authoring, memory).
   - [`references/not-available.md`](references/not-available.md) — real,
     commonly-requested things that **aren't** reachable this way today, and why.
     Check this before spending calls discovering it the hard way.
2. **Treat the reference files as a map, not a schema.** They name real operator URIs
   and what each is for; they deliberately don't restate exact parameters, because
   those can differ by deployment, dataset, and plugin version. Always call
   `get_operator_schema` for the operator you've settled on before calling
   `execute_operator` with anything beyond no/trivial parameters.
3. **`list_operators(dataset_name=...)` is live-permission-filtered.** Use it to
   confirm an operator a reference file names is actually available to this caller
   on this dataset, not to browse — it returns bare URIs with no description.
4. **Delegate long-running work.** `execute_operator(..., delegate=True)` queues a
   background run instead of blocking; check the response's `delegated` field (not
   every operator supports it), then follow up per
   [`references/delegated-operations.md`](references/delegated-operations.md).

## Generating Deeplinks

No MCP tool or FiftyOne SDK call builds a shareable App URL — there's no
`generate_deeplink`, `get_dataset_url`, or similar operator. Build the URL
string yourself from the deployment's own host (the same `<host>` from
Prerequisites, not the gateway's `/api/proxy/...` path) plus these
conventions:

- Dataset: `https://<host>/dataset/<url-encoded-name>`
- A specific sample: append `/sample/<sample-id>`
- A specific group (grouped dataset): append `/group/<group-id>`
- A saved view: `?view=<saved-view-slug>` — only works for views that are
  already saved (have a slug via `save_view`); there's no way to deep-link an
  ad-hoc filtered view's raw stages
- An active group slice: `&slice=<slice-name>`
- One or more panels open beside Samples: `&panel=<name>` or
  `&panel=<name1>,<name2>` — this was built specifically for agent-generated
  links, but the underlying `open_panel` operator is browser-only and not
  reachable via `execute_operator`; it only works by putting it in the URL

Example, a sample with the Model Evaluation panel open:
`https://<host>/dataset/my-dataset/sample/<sample-id>?panel=model_evaluation_panel_builtin`

Don't invent other query parameters, and don't offer a `?share=` link — that
raw-view-stage share param exists in the App's source but isn't wired up to
anything yet.

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `Incompatible auth server: does not support dynamic client registration` when adding the MCP server | The MCP client tried to self-register a client id; this deployment's auth server doesn't support that | Remove and re-add the server with an explicit `--client-id voxel51-agent-mcp` (see Workflow step 2) |
| Pairing approval is refused, mentions a missing permission | The signed-in user approving the pairing doesn't have the `USE_API_KEYS` permission on their account | Ask a FiftyOne admin to grant that permission to the user's account, this is intentional, not a bug |
| An operator you expect isn't in `list_operators` | The connected account's current role or dataset permissions don't allow it | Working as intended, permissions are re-checked live on every call, not cached. Confirm with the account's admin what it should have access to |
| Everything worked, then started failing after a while with an auth error | The access token (short-lived, ~1 hour) expired and the automatic refresh also failed, most likely the pairing was revoked | Reconnect the MCP server |
| MCP tools don't appear right after adding the server | New MCP servers only attach on the next session (Key Directive 6) | Restart the agent / start a fresh conversation |
| User is on OSS FiftyOne, not Voxel51 | This whole feature is Voxel51-only | Point them at the local `fiftyone-mcp` server instead, which needs no pairing |

## Resources

- [Voxel51 documentation](https://docs.voxel51.com/enterprise/index.html)
Files in this package (7)
  • README.md 1 KB
  • SKILL.md 12 KB
  • references/agent-tools.md 2 KB
  • references/analysis-and-labeling.md 4 KB
  • references/datasets-and-samples.md 2 KB
  • references/delegated-operations.md 2 KB
  • references/not-available.md 3 KB

Versions

The database has no other skills named voxel51-agent-setup.

Database snapshot: 13.11.2026 · package version ab26cc6867b0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100mcp-client-integration
    Connect MCP servers to AI clients — Claude Desktop, Claude Code, Cursor, the Claude Agent SDK, and custom apps — including config file locations, auth, and debugging connection failures. Use this skill when the user wants to wire an MCP server into a client, troubleshoot "server…
  • 100agent-auth-mcp
    Use the Agent Auth MCP tools to discover providers, connect agents, manage capabilities, and execute operations through the MCP protocol. Use when working inside an MCP-enabled environment (Cursor, Claude Code, etc.) and need to authenticate agents, execute capabilities, or…
  • 95jev-style-mcp
    Connect the Jev-Style local decision model to an AI coding agent as an MCP server (tools decide, noul, choice, score, model_info) - Claude Code, Claude Desktop, Cursor, Codex CLI, Windsurf or any MCP client. Use when the user wants their agent to classify, route, gate or score…
  • 100render-mcp
    Connects and configures the Render MCP server for AI coding tools—setup per tool (Cursor, Claude Code, Codex), authentication, workspace selection, capability discovery, and troubleshooting. Use when MCP is not configured, list_services() fails, the user asks about Render MCP…
  • 100hub-agent-setup
    Connect a local or remote AI agent to Giskard Hub through an authenticated, non-streaming HTTPS endpoint. Use when a user asks to connect, integrate, or register their agent with the Hub. Build a minimal wrapper, deploy or tunnel it, and use the Hub connection test (SDK or MCP) to guide any fixes.
  • 100connect
    Use when the user wants to connect, set up, or configure Fusionaly in their AI client, or when the fusionaly MCP tools are missing. Verifies the Fusionaly URL and agent key, then adds the MCP server to Claude Code, Codex, Cursor, Gemini CLI, or another client.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.