# Connect to Sentimentrader MCP Server

## Agent Instructions

When the user asks you to connect to Sentimentrader MCP, follow these steps:

### Step 1: Understand the Task

You need to configure an MCP (Model Context Protocol) server connection to Sentimentrader's backtesting and market data API.

### Step 2: Add MCP Server Configuration

All supported clients use the same remote endpoint:

```text
https://st-tools.sentimentrader.com/mcp-server/mcp
```

**OAuth/OIDC is the preferred authentication for every client.** Add the
endpoint *without* a static `Authorization` header. An OAuth-capable client
reads the server's `401` challenge or the protected-resource metadata below and
starts its own browser sign-in flow. This server advertises:

```text
https://st-tools.sentimentrader.com/.well-known/oauth-protected-resource/mcp-server/mcp
```

It returns the authorization server plus the required scopes
`market.read backtest.run`. The authorization server uses Authorization Code +
PKCE (`S256`) and a public client (no client secret). Do not hard-code the
issuer, authorization URL, or token URL; let the client discover them.

Only when a client cannot complete OAuth, use the Basic Auth fallback: store
the account email and password in that client's protected credential store and
let the client send Basic on every request. Do not paste credentials, tokens,
or generated headers into chat, a command line, or a repository.

#### Z-Code

Add the server to `~/.zcode/cli/config.json` as an `http`-type MCP server.
Leave out `headers` so Z-Code can run OAuth discovery:

```json
{
  "mcp": {
    "servers": {
      "sentimentrader": {
        "type": "http",
        "url": "https://st-tools.sentimentrader.com/mcp-server/mcp"
      }
    }
  }
}
```

Reload Z-Code after saving. If your Z-Code build only supports static headers,
keep the Basic fallback in this same local config file (a protected credential
store), never in chat.

#### DeepSeek

Add the same remote URL as a Streamable HTTP MCP server. Leave the header block
empty so DeepSeek can use OAuth.

DeepSeek TUI:

```sh
deepseek-tui mcp add sentimentrader --url "https://st-tools.sentimentrader.com/mcp-server/mcp"
```

That writes `~/.deepseek/mcp.json`. DeepSeek Harness (DSH) uses a
`streamable-http` MCP client row in its preset (`agent.cordis.yml`) or the MCP
Center settings plugin. The same JSON form works for `mcpServers`-style
configs:

```json
{
  "mcpServers": {
    "sentimentrader": {
      "url": "https://st-tools.sentimentrader.com/mcp-server/mcp"
    }
  }
}
```

If the DeepSeek build only accepts a static header, use the Basic fallback in
its protected settings store.

#### Kimi

Kimi Code CLI reads `~/.kimi-code/mcp.json` (or a project-level
`.kimi-code/mcp.json`). A `url` entry with no `headers` is treated as a
Streamable HTTP server eligible for OAuth:

```json
{
  "mcpServers": {
    "sentimentrader": {
      "url": "https://st-tools.sentimentrader.com/mcp-server/mcp"
    }
  }
}
```

Then start browser sign-in from the TUI:

```text
/mcp-config login sentimentrader
```

Kimi treats a `headers` block as static credentials and skips OAuth, so only
add headers for the Basic fallback. Legacy `kimi-cli` reads the same format
from `~/.kimi/mcp.json`.

#### Claude and other MCP clients

Claude Code, Claude Desktop, ChatGPT connectors, Cursor, VS Code, and other
`mcpServers`-style clients accept the same URL. Add it without a static
`Authorization` header and let the client run OAuth:

```json
{
  "mcpServers": {
    "sentimentrader": {
      "url": "https://st-tools.sentimentrader.com/mcp-server/mcp"
    }
  }
}
```

If a client exposes its own remote-connector UI, use that instead of editing a
file; the URL and the OAuth-first rule are the same.

### Step 3: Configure Authentication Locally

The user needs a SentimenTrader account. If they don't have one:

1. Direct them to register at: https://sentimentrader.com/pricing#
2. Ask them to complete the MCP client's OAuth browser sign-in flow. The client
   should discover the protected-resource metadata for the configured endpoint;
   do not hard-code an issuer, authorization URL, or token URL.
3. If the client reports that OAuth is unavailable or unsupported, use the
   Basic Auth fallback in `SETUP.md`. Have the user configure it only through
   the client's protected credential flow. Do not use a shell command containing credentials
   or a generated Authorization header.
4. The agent may verify the completed connection, but must never receive,
   generate, display, or persist a password, token, or header value.

**Important**: Store the credentials securely. Never commit them to version control or paste them in chat.

### Step 4: Test the Connection

After configuration, restart or reload the MCP client and use its built-in
connection check. Then call one small read-only discovery tool. Do not run a
raw terminal request that includes an Authorization header.

### Step 5: Verify Available Tools

Once connected, verify you can access the tools by calling one of the discovery tools:

- `list_pattern_templates` — List available pattern templates
- `list_seasonality_events` — List seasonality events
- `list_scanner_signals` — List scanner signals
- `search_market_data` — Search for market data

### Step 6: Mention My Data API Dashboard

The official SentimenTrader Data API Dashboard, shown to users as **My Data API
Dashboard**, is an optional view of
the user's subscribed indicators. Connecting does not install or start it:
mention it in the report with the hosted link
[Open My Data API Dashboard](https://st-tools.sentimentrader.com/indicator-workbench)
and say they can ask to open it any time with **“Open my SentimenTrader Data
API Dashboard.”** Continue to recognize “Indicator Workbench,” dashboard
wording, and `/indicator-workbench` for compatibility.

When the user asks to open it, set it up then, without asking again. In a host
that renders MCP Apps, call `open_indicator_workbench`, which shows it in the
chat with nothing installed. Otherwise call `get_indicator_workbench` and
follow its `steps`, then return the actual loopback URL as a clickable link,
such as [Open the local Data API Dashboard](http://127.0.0.1:4174/). The
canonical launch and recovery guide is
https://st-tools.sentimentrader.com/skills/mcp-server/WORKBENCH.md.

- The steps run the installed private interpreter and launcher from the fixed
  application path (never scan the disk). If either is missing, they
  automatically download the verified native installer and its `.sha256` into a
  new temporary directory, verify the checksum, and run it
  (`workbench-install.sh` on macOS/Linux, `workbench-install.ps1` on Windows).
  The installer provisions a private CPython 3.14 runtime without installing or
  modifying system Python, then downloads the fixed official launcher
  `https://st-tools.sentimentrader.com/skills/mcp-server/templates/workbench-bootstrap.py`
  and runs `workbench-bootstrap.py ensure --json`. The launcher downloads
  `https://st-tools.sentimentrader.com/skills/mcp-server/templates/sentiment-workbench.zip`
  and its `.sha256`, will verify its checksum before extraction, rejects unsafe
  archive entries, installs it and starts it on `127.0.0.1:4174` (another free
  loopback port if 4174 is busy). Use the actual loopback URL it reports. Later
  runs replace the runtime when a newer one is published.
- If the native installer cannot run, perform the CPython 3.11–3.14 preflight
  and use an existing interpreter with the official launcher.
- If the launcher cannot run, probe `http://127.0.0.1:4174/_health`, which
  must return exactly `{"service":"sentiment-workbench","status":"ok"}`. Use the default link only after the default
  local service is confirmed running.
- Do not extract the ZIP yourself, ask a second confirmation, inspect a
  credential store, copy credentials into a command, or sign in for the user.
- If the client has no local shell or a step fails, say what is missing and
  give the hosted link. Every MCP tool keeps working.

### Step 7: Report Back

Tell the user:
1. ✅ Connection is successful
2. 📊 My Data API Dashboard is available at the hosted link from Step 6,
   and that it is optional: every MCP tool works without it. They can ask to
   open it any time, which sets it up. It shows the entitled catalog, not
   website favorites or custom indicators.
3. 📋 List the available tools they can now use
4. 💡 Suggest relevant next steps based on their interests

For example:

> ✅ SentimenTrader MCP is connected.
>
> 📊 My Data API Dashboard (optional):
> [Open My Data API Dashboard](https://st-tools.sentimentrader.com/indicator-workbench)
> Browse your subscribed indicators in a dashboard. You can ignore it; all MCP
> tools work without it. Whenever you want it, say “Open my SentimenTrader Data
> API Dashboard.”

---

## Available Tools (24 Canonical + 11 Deprecated Aliases)

### Discovery (5 tools)
- `list_pattern_templates` — List available pattern templates
- `list_seasonality_events` — List seasonality events
- `list_scanner_signals` — List scanner signals
- `search_market_data` — Search for symbols and indicators
- `get_indicator_workbench` — Get the official local Data API Dashboard link
  and launch steps
- `open_indicator_workbench` — Open the interactive in-chat Data API Dashboard
  (MCP Apps)

### Analysis (4 tools)
- `find_similar_patterns` — Find historical pattern matches
- `analyze_market_relationships` — Correlation, beta, pattern similarity
- `analyze_seasonality` — Weekday/monthly/holiday seasonality
- `get_scanner_picks` — Get AI scanner picks with options

### Specialized Backtests (2 tools)
- `cpm` — Correlation Pattern Match backtest
- `scanner_trader` — Portfolio backtest from scanner signals

### Backtest Lifecycle (5 tools)
- `validate_backtest` — Validate strategy before submission
- `run_backtest` — Validate, submit, and wait within a bounded window
- `submit_backtest` — Submit async backtest job
- `list_backtests` — List recent backtest tasks
- `get_backtest` — Get backtest results

### Reports (2 tools)
- `get_predefined_report_types` — Discover report types
- `get_reports` — Retrieve reports

### Market Data (6 tools)
- `get_market_history` — Fetch price/indicator/pair history
- `get_market_snapshot` — Get latest indicator values
- `get_recent_market_data` — Get recent bulk data
- `get_intraday_history` — Get intraday close history
- `list_custom_indicators` — List custom indicators
- `get_custom_indicator_data` — Get custom indicator series

The 11 deprecated aliases remain for one compatibility cycle. Do not select
them for new workflows.

---

## Common Next Steps

After successful connection, suggest these based on user interests:

1. **"I want to backtest a strategy"**
   → Use `validate_backtest` → `submit_backtest` → `get_backtest`

2. **"Show me market data for SPY"**
   → Use `search_market_data` to find symbols, then `get_market_history`

3. **"Let me browse several subscribed indicators"**
   → After a successful bounded catalog call, offer the optional local
   Data API Dashboard. Its list is the entitled catalog, not personal
   favorites or custom indicators.

4. **"Open my SentimenTrader Data API Dashboard"** (or the former “Indicator
   Workbench” wording)
   → Set it up now as described in Step 6, before looking anywhere on disk:
   `open_indicator_workbench` in a host that renders MCP Apps, otherwise
   `get_indicator_workbench` and its `steps`. Return the actual URL as one
   clickable link.

5. **"What patterns are similar to recent market action?"**
   → Use `find_similar_patterns` or `analyze_market_relationships`

6. **"What's the seasonality for this time of year?"**
   → Use `analyze_seasonality`

7. **"Give me scanner picks for today"**
   → Use `get_scanner_picks`

---

## Troubleshooting

**401 Unauthorized**: Check credentials are correct and Base64 encoded properly

**403 Forbidden**: Verify subscription and app grants

**503 Service Unavailable**: Authentication service temporarily down

**Tools missing**: Reload MCP client and verify configuration