sequentum-mcp

# Sequentum MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The [Sequentum MCP Server](https://mcp.sequentum.com) connects your AI coding assistant to Sequentum using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), giving your AI tools the ability to create web scraping agents, run management, scheduling, analytics, and more. Sequentum hosts and manages a remote MCP server with OAuth authentication, so there's nothing to install.

## [Tool Reference](./docs/tool-reference.md) | [Prompts Reference](./docs/prompts-reference.md) | [Resources Reference](./docs/resources-reference.md) | [Troubleshooting](./docs/troubleshooting.md) | [Changelog](./CHANGELOG.md)

## Key Features

- **Agent management**: Build, list, search, and get detailed information about your web scraping agents.
- **Run automation**: Start, stop, and monitor agent executions with real-time status tracking.
- **Schedule management**: Create and manage automated schedules using cron expressions.
- **Analytics & diagnostics**: Get run statistics, error analysis, and suggested fixes for failures.
- **Space organization**: Manage agent workspaces and run batch operations across spaces.

## Disclaimers

`sequentum-mcp` exposes your Sequentum account data to MCP clients, allowing them to
view, run, and manage your web scraping agents. Keep your credentials secure and avoid
sharing sensitive information that you don't want accessible to MCP clients.

## Getting Started

Add the Sequentum MCP server to your client with this configuration:

```json
{
  "mcpServers": {
    "sequentum": {
      "url": "https://mcp.sequentum.com/mcp"
    }
  }
}
```

**Most clients support the OAuth configuration.** Claude.ai and Claude Desktop are simpler still — Sequentum MCP is listed in Claude's connector directory, so there is nothing to enter by hand; see [Claude.ai and Claude Desktop](#claudeai-and-claude-desktop) below. For other clients, when you first connect, you'll be prompted to:

1. Log in with your Sequentum account
2. Accept the OAuth authorization
3. Grant access to the necessary permissions

Once authenticated, all tools become available in your client. For client-specific setup details, see [Set Up Your Client](#set-up-your-client) below.

## Set Up Your Client

Select your client below for specific setup instructions. All clients use the remote OAuth server at `https://mcp.sequentum.com/mcp` unless noted otherwise.

### Cursor

Go to `Cursor` > `Settings` > `Cursor Settings` > `MCP` and follow the prompts to add the Sequentum MCP server. Cursor 1.0+ includes native OAuth and Streamable HTTP support.

You can also add the server manually by editing your `mcp.json` file using the [configuration above](#getting-started).

### Claude.ai and Claude Desktop

Sequentum MCP is listed in Claude's connector directory, so there is no URL to enter by hand and no custom connector to create.

1. Open **Settings** and go to **Connectors**.
2. Browse the **Directory**, select **Connectors**, and find **Sequentum MCP**.
3. Click **Connect** and sign in with your Sequentum account.

Team and Enterprise workspaces: connector availability is governed at org level, so an admin may need to enable Sequentum MCP before members can connect from their own accounts.

**Enabling per conversation:** once connected, enable Sequentum in an individual conversation via the **+** button near the message composer, then select **Connectors**.

### ChatGPT

> **Note:** While the Sequentum app is pending directory approval, you can connect via Developer Mode. Apps & Connectors → Developer Mode is currently available on **Plus, Pro, Business, Enterprise, and Education** plans (Education is web-only). On Business / Enterprise / Education accounts, only **workspace owners and admins** can access Advanced settings — regular members will not see the option. See [OpenAI's Developer Mode documentation](https://platform.openai.com/docs/developer-mode) for current eligibility.

1. In ChatGPT, go to **Settings** > **Apps & Connectors** > **Advanced settings** and enable **Developer mode**.
2. Navigate to **Settings** > **Apps & Connectors** and click **Create app** (it appears once Developer mode is enabled).
3. Enter the connector name `Sequentum` and URL: `https://mcp.sequentum.com/mcp`
4. Click **Create**. You'll be prompted to sign in with your Sequentum account via OAuth.

Once connected, enable Sequentum in a conversation via the **+** button near the message composer, then select your connector from the list.

### Claude Code

Connect Sequentum MCP once from the connector directory (see [Claude.ai and Claude Desktop](#claudeai-and-claude-desktop) above) and it is available in Claude Code on the same account.

To add it directly instead — useful per-project or in scripts:

```bash
claude mcp add --transport http sequentum https://mcp.sequentum.com/mcp
```

Then launch Claude Code with `claude` and type `/mcp` to trigger the OAuth browser flow.

### VS Code / GitHub Copilot

Open the Command Palette with `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS) and select `MCP: Add Server`. Enter the Sequentum MCP server URL:

```
https://mcp.sequentum.com/mcp
```

### Windsurf

Configure via the `Configure MCP` option in Cascade (`Cmd+L` or `Ctrl+L`). Add the Sequentum MCP server URL:

```
https://mcp.sequentum.com/mcp
```

### Other Clients

The Sequentum MCP Server follows standard MCP protocols and works with any client that supports:

- **OAuth authentication** (recommended)
- **Streamable HTTP** with automatic SSE fallback

Use the server URL `https://mcp.sequentum.com/mcp` in your client's MCP configuration.

The server supports [Client ID Metadata Documents (CIMD)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00) as the preferred client identification method, with [Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) as a fallback. MCP clients that support CIMD (such as Cursor) can use their own URL as a `client_id` without any prior registration.

## Deprecated: stdio and API-key auth

> **Deprecated:** Running the MCP server locally over the **stdio** transport,
> authenticated with `SEQUENTUM_API_KEY`, is deprecated and will be removed in a future
> release. The `sequentum-mcp` npm package is deprecated along with it. Connect to
> `https://mcp.sequentum.com/mcp` over HTTP with OAuth 2.1 instead — see
> [Set Up Your Client](#set-up-your-client).
>
> This does not affect Sequentum API keys themselves, which remain fully supported for
> the [REST API](https://docs.sequentum.com/api-reference/authentication).

The MCP [authorization specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)
directs stdio implementations not to use OAuth, and to take credentials from the
environment instead. Moving the server to OAuth 2.1 therefore retires the stdio path
along with it — the two deprecations are one decision, not two.

If you are running this configuration today, it keeps working — on Node 20 or later:

```json
{
  "mcpServers": {
    "sequentum": {
      "command": "npx",
      "args": ["-y", "sequentum-mcp"],
      "env": {
        "SEQUENTUM_API_KEY": "sk-your-api-key-here"
      }
    }
  }
}
```

The API key is created in the [Sequentum Control Center](https://dashboard.sequentum.com)
under **Settings** > **API Keys**, and `SEQUENTUM_API_URL` overrides the Sequentum
instance it connects to (default `https://dashboard.sequentum.com`).

To migrate, delete that block and follow the setup instructions for your client above.
If you need Sequentum MCP somewhere that cannot reach `mcp.sequentum.com`, contact
support — there is no supported self-hosted deployment.

## Example Usage

Once connected, try these prompts to start using Sequentum context in your AI assistant:

```
What agents ran yesterday?
Run agent <agent name> now.
Is agent <agent name> still running?
What agents are scheduled to run today?
Download the extracted data from agent <agent name>.
How many records were found the last time <agent name> was run?
What is my current balance?
Which agents cost the most this month?
Schedule agent <agent name> to run every Monday at 9am.
Look at the run log for <agent name> run at 9:22am. What caused the agent to fail?
Show me the cost breakdown for agent <agent name> in January.
What were the most expensive runs for agent <agent name>?
How much did I spend on server time vs exports last week?
```

## Available Tools

The Sequentum MCP Server provides 43 tools across 9 categories for interacting with the Sequentum platform. See the [Tool Reference](./docs/tool-reference.md) for detailed documentation.

<!-- BEGIN AUTO GENERATED TOOLS -->

- **Agent Management** (5 tools)
  - [`list_agents`](docs/tool-reference.md#list_agents)
  - [`get_agent`](docs/tool-reference.md#get_agent)
  - [`search_agents`](docs/tool-reference.md#search_agents)
  - [`get_agent_search_count`](docs/tool-reference.md#get_agent_search_count)
  - [`get_personal_agent_count`](docs/tool-reference.md#get_personal_agent_count)
- **Run Management** (7 tools)
  - [`get_agent_runs`](docs/tool-reference.md#get_agent_runs)
  - [`get_agent_run_summary`](docs/tool-reference.md#get_agent_run_summary)
  - [`get_run_status`](docs/tool-reference.md#get_run_status)
  - [`start_agent`](docs/tool-reference.md#start_agent)
  - [`stop_agent`](docs/tool-reference.md#stop_agent)
  - [`kill_agent`](docs/tool-reference.md#kill_agent)
  - [`delete_run`](docs/tool-reference.md#delete_run)
- **File Management** (2 tools)
  - [`get_run_files`](docs/tool-reference.md#get_run_files)
  - [`get_file_download_url`](docs/tool-reference.md#get_file_download_url)
- **Version Management** (2 tools)
  - [`get_agent_versions`](docs/tool-reference.md#get_agent_versions)
  - [`restore_agent_version`](docs/tool-reference.md#restore_agent_version)
- **Schedule Management** (8 t