sequentum-mcp 1.1.3 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,140 @@
 # Changelog
 
+## [1.3.0] - TBD
+
+### Added
+
+- **ChatGPT Apps support:**
+  - CORS allowlist extended in `src/server/cors.ts` to permit `https://chatgpt.com`, `https://platform.openai.com`, and any subdomain depth under `chatgpt.com` (e.g. `connector.chatgpt.com`). `https://chat.openai.com` is intentionally omitted — OpenAI retired that origin in mid-2024 and redirects it to `chatgpt.com`; no live ChatGPT surface issues that Origin header. Same multi-level subdomain pattern and trust rationale as the Claude entries.
+  - `openWorldHint` added to all 13 write tools per the MCP spec. Tools that scrape arbitrary external websites on behalf of the caller (`start_agent`, `run_space_agents`, `start_agent_build`) are `true`. Tools that only mutate Sequentum's internal state (`stop_agent`, `kill_agent`, `delete_run`, `restore_agent_version`, schedule CRUD, `stop_agent_build`) are `false`. Required by OpenAI's ChatGPT App submission review.
+  - ChatGPT setup instructions added to `README.md` under "Set Up Your Client".
+- **Claude Connectors Directory support:**
+  - Origin-header allowlist (`src/server/cors.ts`) replaces the previous wildcard `Access-Control-Allow-Origin: *`. Permits Claude domains (`claude.ai`, `claude.com`, and all subdomain depths), Sequentum domains, and (when `DEBUG=1`) localhost / `127.0.0.1` / `[::1]`. Additional exact-match origins can be appended at startup via `ALLOWED_ORIGINS` (comma-separated; defaults are always preserved — see README). Requests from non-allowlisted browser origins to `/mcp` receive 403; requests without an `Origin` header (native MCP clients such as Cursor, Claude Desktop, Claude Code) pass through unaffected. `Vary: Origin` is set unconditionally so intermediate caches cannot conflate responses across origins.
+  - Privacy Policy section added to `README.md` with a plain-language data-handling summary and a link to `https://www.sequentum.com/privacy-policy`.
+- **Agent Builder tools** (3 new tools):
+  - `start_agent_build` — Start an AI-powered agent build session from a natural language prompt. The agent is saved to the workspace automatically once the AI creates it.
+  - `get_agent_build_status` — Poll the status of an agent build session. Stop polling on any terminal status: `completed`, `ready`, `error`, or `cancelled`. The session tears down automatically.
+  - `stop_agent_build` — Abort an in-progress build session early (optional). Has no effect once a terminal status is reached. Any agent already saved to the workspace persists.
+- **Agent Building prompts** (2 new prompts):
+  - `build-agent-from-prompt` — End-to-end workflow: resolve space, start session, poll until complete, fetch and show the resulting agent
+  - `inspect-agent-draft` — Check the status of an existing build session and show the resulting agent once available
+- **`validateString` extended** with `minLength`, `maxLength`, and `trim` options (via new `StringValidationOptions` interface). Fully backward-compatible — existing callers that pass a boolean are unaffected.
+- New types in `src/api/types.ts`: `AgentBuilderSessionStatus`, `ExternalStartAgentBuildRequest`, `ExternalStartAgentBuildResponse`, `ExternalSessionStatusResponse`
+- **User-controlled polling cadence for Agent Builder:**
+  - Added optional `pollingPreference` argument to both `build-agent-from-prompt` and `inspect-agent-draft` prompts. Accepts `"fast"` / `"normal"` / `"slow"` or any free-form instruction (e.g. `"poll every 5 seconds"`, `"be patient, this is a big site"`). When provided, the directive is templated into the prompt as a high-priority instruction the model honors when polling `get_agent_build_status`.
+  - Added a `POLLING CADENCE` paragraph to the `get_agent_build_status` tool description so user-expressed cadence preferences are also respected when the tool is invoked outside the prompts (e.g. via plain-chat usage). Default is a moderate cadence with backoff (~5s start, ~15–30s ceiling).
+- `title` annotation added to all 39 tools — human-readable label used by Anthropic's Connectors Directory and OpenAI's ChatGPT App submission.
+- `destructiveHint: false` explicitly set on `start_agent_build` and `stop_agent_build` (previously defaulted to `true` because `readOnlyHint: false` was set without `destructiveHint`).
+- **Sufficiency and prompt-handling policies.** New `src/server/policies.ts` is the single source of truth for two LLM-facing policy strings:
+  - `SUFFICIENCY_POLICY` is sent to every MCP client as the server `instructions` (on `initialize`). Directs the model to ask one consolidated clarifying question when a build/run request lacks an unambiguous URL, target data, or scope qualifier, and explicitly forbids silent extrapolation by analogy across sites or schemas.
+  - `PROMPT_HANDLING_POLICY` is appended to the `start_agent_build` tool description and inlined into the `build-agent-from-prompt` prompt template (rendered as a `**GUARDRAIL:**` preamble before the numbered steps). Directs the model to pass the user's wording through verbatim, allow only trivial normalizations (e.g. adding `https://`), and never invent fields, output formats, lazy-load instructions, pagination strategies, etc.
+  - Net behavior change: the model asks for missing details instead of silently expanding sparse user input into verbose `start_agent_build` prompts.
+
+### Documentation
+
+- `docs/tool-reference.md` — Updated count to 39 tools, new Agent Builder category in Quick Reference and full section
+- `docs/prompts-reference.md` — Updated count to 9 prompts, new Agent Building category in Quick Reference and full sections for both prompts
+- `docs/resources-reference.md` — Added cross-reference note explaining that saved agents become accessible via existing `sequentum://agents/{agentId}` resource
+
+### Security
+
+- Prompt arguments (`prompt`, `spaceName`, `sessionId`, `pollingPreference`) in `src/server/prompts.ts` are now sanitized before interpolation: newlines stripped, trimmed, and enforced per-argument length limits. Reduces prompt-injection surface via user-controlled strings.
+- `pollingPreference` de-elevated from an `IMPORTANT DIRECTIVE` banner to an advisory instruction, reducing its authority in the model's context.
+- `get_agent_build_status` handler now wraps raw backend `error` messages with a generic user-facing string (`"Build failed. Please review your prompt and try again."`). Raw error is still logged at `DEBUG=1` for operators. Prevents leakage of backend stack traces or internal endpoint paths to clients.
+- `sessionId` parameter validated with `maxLength: 256` at both agent-builder handler call sites.
+- `stop_agent_build` handler now returns structured JSON (`{ stopped: true, sessionId }`) instead of free-form English prose, consistent with all other tool handlers.
+- `redactDebugArgs` in `src/server/handlers.ts` extended to mask `prompt` and `comments` fields in addition to existing sensitive keys.
+- The new sufficiency and prompt-handling policies (see **Added**) reduce the surface for the model to silently extrapolate user requests across sites or schemas — defense in depth against accidental leakage of inferred-but-wrong details into a build.
+
+### Tests
+
+- Annotation regression tests strengthened in `src/server/handlers.test.ts`: every tool must have a non-empty `title` and `readOnlyHint` defined. Write-tool annotations are now validated against per-tool expectation tables — `openWorldHint` and `destructiveHint` must match an explicit expected value, not just be defined. Adding a new write tool without classifying both hints fails the build; changing an existing value without updating the table also fails.
+- Handler-dispatch tests added for the three agent-builder tools via `InMemoryTransport` + `Client`: `start_agent_build` rejects prompts below `minLength: 10`; `get_agent_build_status` sanitizes the `error` field; `stop_agent_build` returns the expected JSON shape.
+- CORS regression tests added in `src/server/cors.test.ts` covering exact-origin matches, claude/chatgpt subdomain depth (single and multi-level), `ALLOWED_ORIGINS` env-var append semantics, debug-mode localhost / IPv6 loopback, and adversarial rejections (e.g. `https://claude.ai.evil.com`, `https://notclaude.ai`, wrong scheme, uppercase).
+- Policy-wiring regression tests added in `src/server/handlers.test.ts`: `client.getInstructions()` equals `SUFFICIENCY_POLICY`; the `start_agent_build` tool description contains `PROMPT_HANDLING_POLICY`; the `build-agent-from-prompt` template embeds `PROMPT_HANDLING_POLICY`. Ensures the constants reach all three injection surfaces and prevents silent drift.
+
+---
+
+## [1.2.0] - 2026-03-12
+
+### Added
+
+- **MCP Prompts** (9 reusable workflow templates):
+  - `debug-agent` -- Diagnose why an agent is failing
+  - `agent-health-check` -- Comprehensive health overview for an agent
+  - `spending-report` -- Spending and credits report
+  - `cost-analysis` -- Analyze costs across agents
+  - `run-and-monitor` -- Start an agent and monitor until completion
+  - `space-overview` -- Overview of all agents in a space
+  - `daily-operations-report` -- Daily operations report across all agents
+  - `schedule-agent` -- Walk through creating or reviewing schedules
+  - `compare-runs` -- Compare last successful vs failed run
+- **MCP Resources** (18 read-only, URI-addressable data endpoints):
+  - 7 static resources: agent list, spaces, credits balance, monthly spending, agent costs, recent runs summary, upcoming schedules
+  - 11 resource templates: agent detail, agent versions, agent schedules, agent cost breakdown, agent runs, run status, run files, run diagnostics, latest failure, space detail, space agents
+- **Schedule Management** tools:
+  - `get_agent_schedule` -- Get details of a specific schedule
+  - `update_agent_schedule` -- Update an existing schedule's timing, parameters, or settings
+  - `enable_agent_schedule` -- Enable a previously disabled schedule
+  - `disable_agent_schedule` -- Disable a schedule without deleting it
+- New `src/server/handlers.test.ts` with handler unit tests
+- Expanded test coverage for API client and index module
+- Documentation: `docs/prompts-reference.md` and `docs/resources-reference.md`
+
+### Changed
+
+- **Major architecture refactoring**: Split monolithic `src/index.ts` (~2000 lines) into a modular structure:
+  - `src/server/tools.ts` -- Tool definitions and schemas
+  - `src/server/handlers.ts` -- MCP server factory and tool handler dispatch
+  - `src/server/http-server.ts` -- HTTP/Streamable transport, session management, OAuth discovery
+  - `src/server/prompts.ts` -- Prompt definitions and message builders
+  - `src/server/resources.ts` -- Resource and resource template definitions with URI dispatcher
+  - `src/api/api-client.ts` -- API client (moved from `src/`)
+  - `src/api/types.ts` -- TypeScript interfaces and enums (moved from `src/`)
+  - `src/utils/validation.ts` -- Input validation helpers (moved from `src/`)
+  - `src/utils/oauth-metadata.ts` -- OAuth metadata builder (moved from `src/`)
+- Extracted shared validation logic into `src/utils/validation.ts` to eliminate duplicate code
+- Added URI validation for resource endpoints
+- Improved atomic session control in HTTP server
+- Updated `docs/tool-reference.md` with the 4 new schedule tools (36 total)
+- Updated `README.md` with prompts, resources sections and references to new documentation
+
+## [1.1.4] - 2026-03-04
+
+### Added
+
+- `delete_run` tool for deleting runs and associated data (PII compliance)
+- **Billing & Cost Analysis** tools for detailed agent cost tracking:
+  - `get_agents_usage` - Get all agents with their costs for a date range, with filtering and sorting options
+  - `get_agent_cost_breakdown` - Get cost breakdown by usage type for a specific agent over time (for charting)
+  - `get_agent_runs_cost` - Get individual run costs for a specific agent with detailed run information
+
+### Changed
+
+- Replaced Claude Desktop setup instructions with Custom Connectors approach (config file method caused Claude Desktop to break). Added plan-specific steps for Free/Pro/Max and Team/Enterprise accounts, with a link to [Claude's custom connectors documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+
+## [1.1.3] - 2026-02-17
+
+### Added
+
+
+- `kill_agent` tool for forceful agent termination (as a last resort when `stop_agent` fails)
+- OAuth 2.1 support with HTTP Streamable transport and RFC 8707 resource parameters
+- OAuth2 Protected Resource Metadata endpoint for MCP client authentication
+- Support for Dynamic Client Registration (DCR) and Client Instance Metadata Discovery (CIMD)
+- New `oauth-metadata.ts` module for OAuth metadata handling
+- Dockerfile for containerized deployment
+
+### Changed
+
+- Enhanced `kill_agent` tool with improved functionality
+- Improved 401 authentication error handling on the `/mcp` endpoint
+- Refactored OAuth-related logic out of `index.ts` into dedicated `oauth-metadata.ts` module
+- Shortened MCP tool descriptions to save tokens
+- Removed unnecessary logging from authentication flow
+- Updated README with OAuth server setup instructions and improved readability
+- Improved `docs/tool-reference.md` and `docs/troubleshooting.md` documentation
+
 ## [1.0.2] - 2026-01-20
 
 ### Fixed
@@ -56,7 +191,9 @@
 
 ---
 
-[Unreleased]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.2...HEAD
+[1.2.0]: https://github.com/Sequentum/sequentum-mcp/compare/v1.1.4...v1.2.0
+[1.1.4]: https://github.com/Sequentum/sequentum-mcp/compare/v1.1.3...v1.1.4
+[1.1.3]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.2...v1.1.3
 [1.0.2]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/Sequentum/sequentum-mcp/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/Sequentum/sequentum-mcp/releases/tag/v1.0.0

package/README.md

@@ -3,12 +3,9 @@
 [![npm version](https://img.shields.io/npm/v/sequentum-mcp.svg)](https://www.npmjs.com/package/sequentum-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-`sequentum-mcp` lets your AI coding assistant (such as Claude, Cursor, or Copilot)
-control and manage your Sequentum web scraping agents. It acts as a Model Context Protocol
-(MCP) server, giving your AI assistant access to the full power of the Sequentum platform
-for agent automation, monitoring, and data extraction.
+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 direct access to 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) | [Troubleshooting](./docs/troubleshooting.md) | [Changelog](./CHANGELOG.md)
+## [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
 
@@ -21,22 +18,132 @@ for agent automation, monitoring, and data extraction.
 ## Disclaimers
 
 `sequentum-mcp` exposes your Sequentum account data to MCP clients, allowing them to
-view, run, and manage your web scraping agents. Keep your API key secure and avoid
+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.
 
-## Requirements
+## Getting Started
 
-- [Node.js](https://nodejs.org/) v18 or higher
-- [npm](https://www.npmjs.com/)
-- Sequentum account with API access
+Add the Sequentum MCP server to your client with this configuration:
 
-## Getting Started
+```json
+{
+  "mcpServers": {
+    "sequentum": {
+      "url": "https://mcp.sequentum.com/mcp"
+    }
+  }
+}
+```
+
+**Most clients support the OAuth configuration.** Claude Desktop uses a different setup via Custom Connectors — see [Claude Desktop](#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 Desktop
+
+> **Note:** Custom connectors are currently in beta. Free plan users are limited to one custom connector.
+
+Claude Desktop connects to remote MCP servers using **Custom Connectors** rather than the config file. The setup differs based on your plan type. For full details, see [Claude's custom connectors documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
+
+**Free, Pro, and Max plans:**
+
+1. Navigate to **Settings** > **Connectors**.
+2. Click **"Add custom connector"** at the bottom of the section.
+3. Enter the Sequentum MCP server URL: `https://mcp.sequentum.com/mcp`
+4. Click **"Add"** to finish.
+
+**Team and Enterprise plans:**
+
+An Owner or Primary Owner must first add the connector to the organization:
+
+1. Navigate to **Organization settings** > **Connectors**.
+2. Click **"Add custom connector"** at the bottom of the section.
+3. Enter the Sequentum MCP server URL: `https://mcp.sequentum.com/mcp`
+4. Click **"Add"** to finish.
+
+Then, each team member connects individually:
+
+1. Navigate to **Settings** > **Connectors**.
+2. Find the Sequentum connector in the list (it will have a "Custom" label).
+3. Click **"Connect"** to authenticate.
+
+**Enabling per conversation:**
+
+Once configured, enable the Sequentum connector in individual conversations via the **"+"** button on the lower left of the chat interface, then select **"Connectors"**.
 
-There are two ways to connect to the Sequentum MCP: running locally with an API key, or connecting to a remote server with OAuth authentication.
+### ChatGPT
 
-### Option 1: Local (API Key)
+> **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.
 
-Run the MCP server locally using `npx`. Add the following config to your MCP client:
+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
+
+Run the following command in your terminal:
+
+```bash
+claude mcp add --transport http sequentum https://mcp.sequentum.com/mcp
+```
+
+Then launch Claude Code with `claude`. You'll be prompted to authenticate with OAuth to Sequentum.
+
+### 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.
+
+## Alternative: Local Setup (API Key)
+
+If you prefer to run the MCP server locally (e.g., for custom deployments, offline use, or CI/CD pipelines), you can use `npx` with an API key instead of the hosted OAuth server.
+
+**Requirements for local setup:**
+
+- [Node.js](https://nodejs.org/) v18 or higher
+- [npm](https://www.npmjs.com/)
+- Sequentum API key
+
+Add the following config to your MCP client:
 
 ```json
 {
@@ -52,64 +159,61 @@ Run the MCP server locally using `npx`. Add the following config to your MCP cli
 }
 ```
 
-#### Get Your API Key
+### Get Your API Key
 
 1. Log in to the [Sequentum Control Center](https://dashboard.sequentum.com)
-2. Go to **Settings** → **API Keys**
+2. Go to **Settings** > **API Keys**
 3. Click **Create API Key** and copy the generated key (starts with `sk-`)
 
-### Option 2: Remote Server (OAuth)
+### Custom Sequentum Instance
 
-Connect to a hosted Sequentum MCP server using OAuth 2.0 authentication. Add the following config to your MCP client:
+To connect to a custom Sequentum deployment, add the `SEQUENTUM_API_URL` environment variable:
 
 ```json
 {
   "mcpServers": {
     "sequentum": {
-      "url": "https://mcp.sequentum.com/mcp"
+      "command": "npx",
+      "args": ["-y", "sequentum-mcp"],
+      "env": {
+        "SEQUENTUM_API_KEY": "sk-your-api-key-here",
+        "SEQUENTUM_API_URL": "https://your-custom-instance.sequentum.com"
+      }
     }
   }
 }
 ```
 
-> **QA environment:** Use `https://mcp-qa.sequentum.com/mcp` instead for testing against the QA server.
-
-When you connect for the first time, your MCP client will open a browser window for you to log in with your Sequentum account.
-
-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.
-
-### MCP Client Configuration Files
+### Local Environment Variables
 
-| Client | Config File Location |
-|--------|---------------------|
-| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
-| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Cursor | `Cursor Settings` → `MCP` → `New MCP Server` |
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SEQUENTUM_API_KEY` | Yes | -- | Your Sequentum API key (format: `sk-...`). Get this from the Sequentum Control Center under Settings > API Keys. |
+| `SEQUENTUM_API_URL` | No | `https://dashboard.sequentum.com` | The base URL of your Sequentum instance. Override if using a custom deployment. |
 
-## Your First Prompt
+## Example Usage
 
-Enter the following prompt in your MCP client to check if everything is working:
+Once connected, try these prompts to start using Sequentum context in your AI assistant:
 
 ```
 What agents ran yesterday?
-```
-
-Your MCP client should return a list of your Sequentum agents with their IDs, names, and status.
-
-### Other Useful Prompts
-
-```
 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?
 ```
 
-## Tools
+## Available Tools
+
+The Sequentum MCP Server provides 39 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 -->
 
@@ -117,27 +221,35 @@ Look at the run log for <agent name> run at 9:22am. What caused the agent to fai
   - [`list_agents`](docs/tool-reference.md#list_agents)
   - [`get_agent`](docs/tool-reference.md#get_agent)
   - [`search_agents`](docs/tool-reference.md#search_agents)
-- **Run Management** (5 tools)
+- **Run Management** (6 tools)
   - [`get_agent_runs`](docs/tool-reference.md#get_agent_runs)
   - [`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** (4 tools)
+- **Schedule Management** (8 tools)
   - [`list_agent_schedules`](docs/tool-reference.md#list_agent_schedules)
+  - [`get_agent_schedule`](docs/tool-reference.md#get_agent_schedule)
   - [`create_agent_schedule`](docs/tool-reference.md#create_agent_schedule)
+  - [`update_agent_schedule`](docs/tool-reference.md#update_agent_schedule)
+  - [`enable_agent_schedule`](docs/tool-reference.md#enable_agent_schedule)
+  - [`disable_agent_schedule`](docs/tool-reference.md#disable_agent_schedule)
   - [`delete_agent_schedule`](docs/tool-reference.md#delete_agent_schedule)
   - [`get_scheduled_runs`](docs/tool-reference.md#get_scheduled_runs)
-- **Billing & Credits** (3 tools)
+- **Billing & Credits** (6 tools)
   - [`get_credits_balance`](docs/tool-reference.md#get_credits_balance)
   - [`get_spending_summary`](docs/tool-reference.md#get_spending_summary)
   - [`get_credit_history`](docs/tool-reference.md#get_credit_history)
+  - [`get_agents_usage`](docs/tool-reference.md#get_agents_usage)
+  - [`get_agent_cost_breakdown`](docs/tool-reference.md#get_agent_cost_breakdown)
+  - [`get_agent_runs_cost`](docs/tool-reference.md#get_agent_runs_cost)
 - **Space Management** (5 tools)
   - [`list_spaces`](docs/tool-reference.md#list_spaces)
   - [`get_space`](docs/tool-reference.md#get_space)
@@ -149,64 +261,111 @@ Look at the run log for <agent name> run at 9:22am. What caused the agent to fai
   - [`get_records_summary`](docs/tool-reference.md#get_records_summary)
   - [`get_run_diagnostics`](docs/tool-reference.md#get_run_diagnostics)
   - [`get_latest_failure`](docs/tool-reference.md#get_latest_failure)
+- **Agent Builder** (3 tools)
+  - [`start_agent_build`](docs/tool-reference.md#start_agent_build)
+  - [`get_agent_build_status`](docs/tool-reference.md#get_agent_build_status)
+  - [`stop_agent_build`](docs/tool-reference.md#stop_agent_build)
 
 <!-- END AUTO GENERATED TOOLS -->
 
-## Configuration
+## Available Prompts
+
+The server includes 9 reusable prompt templates that guide the AI through common multi-step workflows. See the [Prompts Reference](./docs/prompts-reference.md) for detailed documentation.
+
+<!-- BEGIN AUTO GENERATED PROMPTS -->
+
+- **Debugging & Diagnostics**
+  - [`debug-agent`](docs/prompts-reference.md#debug-agent) -- Diagnose why an agent is failing
+  - [`compare-runs`](docs/prompts-reference.md#compare-runs) -- Compare last successful vs failed run
+- **Health & Monitoring**
+  - [`agent-health-check`](docs/prompts-reference.md#agent-health-check) -- Comprehensive health overview for an agent
+  - [`daily-operations-report`](docs/prompts-reference.md#daily-operations-report) -- Daily ops report across all agents
+  - [`space-overview`](docs/prompts-reference.md#space-overview) -- Overview of all agents in a space
+- **Execution**
+  - [`run-and-monitor`](docs/prompts-reference.md#run-and-monitor) -- Start an agent and monitor until completion
+  - [`schedule-agent`](docs/prompts-reference.md#schedule-agent) -- Walk through creating a schedule
+- **Billing & Costs**
+  - [`spending-report`](docs/prompts-reference.md#spending-report) -- Spending and credits report
+  - [`cost-analysis`](docs/prompts-reference.md#cost-analysis) -- Analyze costs across agents
+- **Agent Building**
+  - [`build-agent-from-prompt`](docs/prompts-reference.md#build-agent-from-prompt) -- Build a new agent from a natural language description
+  - [`inspect-agent-draft`](docs/prompts-reference.md#inspect-agent-draft) -- Inspect a build session and decide whether to save or discard
+
+<!-- END AUTO GENERATED PROMPTS -->
+
+## Available Resources
+
+The server exposes 18 read-only resources (7 static + 11 templates) that AI clients can browse and pull into context. See the [Resources Reference](./docs/resources-reference.md) for detailed documentation.
+
+<!-- BEGIN AUTO GENERATED RESOURCES -->
+
+- **Static Resources** (7)
+  - [`sequentum://agents`](docs/resources-reference.md#agent-list) -- First page of all agents
+  - [`sequentum://spaces`](docs/resources-reference.md#spaces) -- All accessible spaces
+  - [`sequentum://billing/balance`](docs/resources-reference.md#credits-balance) -- Current credits balance
+  - [`sequentum://billing/spending`](docs/resources-reference.md#monthly-spending) -- Monthly spending summary
+  - [`sequentum://billing/agents-usage`](docs/resources-reference.md#agent-costs-current-month) -- Top agents by cost
+  - [`sequentum://analytics/runs`](docs/resources-reference.md#recent-runs-summary) -- Runs in the last 24 hours
+  - [`sequentum://analytics/upcoming-schedules`](docs/resources-reference.md#upcoming-schedules) -- Scheduled runs for next 7 days
+- **Resource Templates** (11)
+  - [`sequentum://agents/{agentId}`](docs/resources-reference.md#agent-detail) -- Agent detail with configuration
+  - [`sequentum://agents/{agentId}/versions`](docs/resources-reference.md#agent-versions) -- Agent version history
+  - [`sequentum://agents/{agentId}/schedules`](docs/resources-reference.md#agent-schedules) -- Agent scheduled tasks
+  - [`sequentum://agents/{agentId}/cost-breakdown`](docs/resources-reference.md#agent-cost-breakdown) -- Agent cost by usage type
+  - [`sequentum://agents/{agentId}/runs`](docs/resources-reference.md#agent-runs) -- Agent run history
+  - [`sequentum://agents/{agentId}/runs/{runId}`](docs/resources-reference.md#run-status) -- Specific run status
+  - [`sequentum://agents/{agentId}/runs/{runId}/files`](docs/resources-reference.md#run-files) -- Run output files
+  - [`sequentum://agents/{agentId}/runs/{runId}/diagnostics`](docs/resources-reference.md#run-diagnostics) -- Run error diagnostics
+  - [`sequentum://agents/{agentId}/latest-failure`](docs/resources-reference.md#latest-failure) -- Most recent failure diagnostics
+  - [`sequentum://spaces/{spaceId}`](docs/resources-reference.md#space-detail) -- Space details
+  - [`sequentum://spaces/{spaceId}/agents`](docs/resources-reference.md#space-agents) -- Agents in a space
+
+<!-- END AUTO GENERATED RESOURCES -->
 
-The Sequentum MCP server supports the following environment variables:
+## Troubleshooting
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `SEQUENTUM_API_KEY` | Yes | — | Your Sequentum API key (format: `sk-...`). Get this from the Sequentum Control Center under Settings → API Keys. |
-| `SEQUENTUM_API_URL` | No | `https://dashboard.sequentum.com` | The base URL of your Sequentum instance. Override if using a custom deployment. |
+| Error | Solution |
+|-------|----------|
+| OAuth login not opening | Ensure your client supports OAuth and Streamable HTTP. Try restarting the client. For Claude Desktop, use [Custom Connectors](#claude-desktop) instead of the config file. |
+| Connection refused | Verify the URL is `https://mcp.sequentum.com/mcp` and check your network connection. |
+| `SEQUENTUM_API_KEY required` | Local mode only. Add your API key to the `env` section of the MCP config. |
+| `API Error 401: Unauthorized` | Your API key or OAuth token is invalid or expired. Re-authenticate or generate a new key. |
+| `API Error 404: Not Found` | The agent, run, or file doesn't exist, or you don't have access to it. |
+| `API Error 429: Too Many Requests` | Rate limit exceeded. Wait a moment and try again. |
 
-Pass them via the `env` property in the JSON configuration:
+For more troubleshooting help, see the [Troubleshooting Guide](./docs/troubleshooting.md).
 
-```json
-{
-  "mcpServers": {
-    "sequentum": {
-      "command": "npx",
-      "args": ["-y", "sequentum-mcp"],
-      "env": {
-        "SEQUENTUM_API_KEY": "sk-your-api-key-here"
-      }
-    }
-  }
-}
-```
+## CORS Origin Allowlist
 
-To use a custom Sequentum instance, add the `SEQUENTUM_API_URL`:
+When the MCP server is accessed from a browser (e.g. the Claude web app or the ChatGPT connector), it checks the `Origin` header against an allowlist.  By default the following origins are permitted:
+
+- `https://claude.ai`, `https://claude.com`, and all subdomains (e.g. `team.claude.ai`)
+- `https://chatgpt.com`, `https://platform.openai.com`, and all subdomains under `chatgpt.com` (e.g. `connector.chatgpt.com`)
+- `https://dashboard.sequentum.com`
+- `https://mcp.sequentum.com`
+- `http://localhost:<port>`, `http://127.0.0.1:<port>`, and `http://[::1]:<port>` when `DEBUG=1`
+
+To add your own origins (e.g. an internal dashboard), set the `ALLOWED_ORIGINS` environment variable to a comma-separated list of exact origins:
 
-```json
-{
-  "mcpServers": {
-    "sequentum": {
-      "command": "npx",
-      "args": ["-y", "sequentum-mcp"],
-      "env": {
-        "SEQUENTUM_API_KEY": "sk-your-api-key-here",
-        "SEQUENTUM_API_URL": "https://your-custom-instance.sequentum.com"
-      }
-    }
-  }
-}
+```
+ALLOWED_ORIGINS="https://my-dashboard.example.com,https://other.example.com"
 ```
 
-## Troubleshooting
+These origins are **appended** to the defaults — Claude, ChatGPT, and Sequentum access is preserved.  Wildcards and regular expressions are not supported via the env var; if you need a subdomain wildcard, add a `RegExp` entry directly in `src/server/cors.ts`.
 
-| Error | Solution |
-|-------|----------|
-| `SEQUENTUM_API_KEY required` | Add your API key to the `env` section of the MCP config |
-| `API Error 401: Unauthorized` | Your API key is invalid or expired. Generate a new one from the Control Center. |
-| `API Error 404: Not Found` | The agent, run, or file doesn't exist, or you don't have access to it. |
-| `API Error 429: Too Many Requests` | Rate limit exceeded. Wait a moment and try again. |
+> **Note:** `Origin` matching is case-sensitive and does not include a path or query string.  Native MCP clients (Cursor, Claude Desktop, Claude Code) send no `Origin` header and are not affected by this allowlist.
 
-For more troubleshooting help, see the [Troubleshooting Guide](./docs/troubleshooting.md).
+## Privacy Policy
+
+The Sequentum MCP Server accesses your Sequentum account data — including agent metadata, run history, scheduled tasks, billing information, and output files — solely to fulfill the requests you make through your AI assistant. By default, the MCP server acts as an authenticated proxy between your MCP client and the Sequentum API: request data is forwarded to the API and responses are returned to your client without being persisted or shared with third parties.
+
+Operators may enable verbose request logging via the `DEBUG=1` environment variable for troubleshooting. In that mode the server redacts `Authorization`, `Cookie`, and `x-api-key` headers, but writes request bodies (which may include tool arguments) to stderr. The hosted server at `mcp.sequentum.com` does not run with `DEBUG=1`.
+
+For the full Sequentum privacy policy, see [https://www.sequentum.com/privacy-policy](https://www.sequentum.com/privacy-policy).
 
 ## Links
 
+- [Sequentum MCP Server](https://mcp.sequentum.com)
 - [Sequentum Dashboard](https://dashboard.sequentum.com)
 - [Sequentum API Documentation](https://dashboard.sequentum.com/api-docs/index.html)
 - [Model Context Protocol](https://modelcontextprotocol.io/)