# Set up DeepSieve for your coding agent

## Overview

This file sets up DeepSieve — a deep-research API that returns a **cited
dataset, re-verified while monitoring is on** — inside the coding agent that is
reading it.

You are the agent executing this setup. Work through the steps in order.

The workflow:

- Detecting which coding agent you are and what it supports
- Connecting the DeepSieve MCP server (browser login, or an API key when headless)
- Installing the DeepSieve Agent Skill
- Saving the DeepSieve rules file into this project
- Optionally installing the CLI, if the user works in a terminal
- Verifying the connection end to end
- Reporting what the human can do next

Deployment being configured: **https://deepsieve.ai**

## Parameters

- `origin` (required): the DeepSieve deployment base URL. It is **https://deepsieve.ai** —
  already resolved from where you fetched this file. You MUST NOT ask the user
  for it and MUST NOT substitute a different host.
- `mcp_server_name` (optional): what to name the MCP server in the agent's
  config. Default **`deepsieve`**. Keep the default unless the user asks
  otherwise, or unless that name is already taken by a different origin.
- `api_key` (optional, headless only): a `ds_live_…` key. Required **only** when
  the environment cannot open a browser (CI, containers, remote shells).

Constraints for parameter acquisition:

- You MUST detect the agent and the environment automatically before asking the
  user anything.
- You MUST NOT ask the user to paste an API key into this conversation when the
  browser login path is available. Chat transcripts get logged and shared;
  a browser login leaks nothing.
- If you do need a key (headless only), you MUST tell the user to put it in the
  environment (e.g. `DEEPSIEVE_API_KEY` in `.env`, git-ignored) and reference it
  from config — never inline the secret into a config file you write, and never
  echo it back.

## Dependencies

Constraints:

- You MUST verify `curl` is available (used to fetch the rules file and verify).
- `npx` (Node 18+) is needed for the Agent Skill install in Step 4. If it is
  missing, Step 4 has a no-Node fallback — do not abort the whole setup.
- You MUST inform the user about any missing tool with a clear message, and ask
  whether to proceed without it.
- You MUST respect the user's decision to abort at any point.
- You MUST explain what each step does, why, and which command you are running,
  before you run it.
- You MUST NOT install a global runtime, change the user's shell configuration,
  or modify files outside this project and the agent's own config directory.

## Cost and safety constraints

DeepSieve research runs **cost real money** (prepaid credits) and take 15–60
minutes. Setup must never spend any.

- You MUST NOT start a real research run during setup, at any point, for any
  reason — including "to check it works".
- Verification uses read-only calls only (Step 7). If you want to exercise a
  full run loop afterwards, use `"dry_run": true`, which is free, completes in
  about 15 seconds, and persists nothing.
- You MUST NOT create, modify, or delete API keys on the user's behalf beyond
  what Step 3's headless path explicitly describes.

## General error handling

Precedence, so a failure in a side step cannot abandon the setup:

- **Steps 1, 2, 3 are required.** A failure not covered by that step's error
  table: report the full output and STOP.
- **Steps 4, 5 and 6 are independent and skippable.** Report the failure, say
  which step you skipped and why, and CONTINUE. Step 6 is optional entirely.
- **Step 7 (verify) MUST always run** if Steps 2–3 succeeded, even when a later
  step failed — the user needs to know whether the connection works.

Never fabricate a success. If you could not verify in Step 7, say so.

## Steps

### Step 1: Identify the agent and environment

Determine three things about yourself and where you are running:

1. **Which coding agent you are** (Claude Code, Cursor, VS Code / GitHub
   Copilot, Codex, Windsurf, Gemini CLI, or another).
2. **Whether you support MCP over HTTP** (a remote MCP server at a URL). Most
   modern agents do.
3. **Whether a human can complete a browser login right now** — i.e. this is an
   interactive session on a machine with a browser, not CI, a container, or a
   detached remote shell.

4. **Whether the user already has a DeepSieve account.** If you do not know,
   ask: "Do you already have a DeepSieve account at https://deepsieve.ai?" If they do not,
   tell them to sign up at https://deepsieve.ai first (it takes a minute, and the same
   login is what authorises this agent) — then continue. Do NOT try to create an
   account for them.

**Success:** you can name the agent and have answered (2), (3) and (4).

**Then check whether this deployment offers remote browser login.** Not every
deployment enables remote OAuth; where it is off, the remote endpoint returns 404
and the Authenticate button never works — so you MUST detect this before choosing
the browser path rather than dead-ending on it:

```bash
curl -sL -o /dev/null -w "%{http_code}" https://deepsieve.ai/.well-known/oauth-protected-resource
```

- **`200`** — remote OAuth is live; the browser path (Step 2A) is available.
- **`404`** — this deployment has no remote OAuth. You MUST skip Step 2A and use
  the local stdio / API-key path (Step 2B), **even if a browser is available** —
  registering the HTTP endpoint here leaves the user on an inoperative
  Authenticate button.
- **anything else, or no response** — treat remote OAuth as unavailable and prefer
  Step 2B; do not gamble on a browser flow you could not confirm.

Then choose the path:

- **Supports HTTP MCP, a browser is available, AND remote OAuth returned `200`** →
  Step 2A (recommended).
- **Supports MCP, but no browser _or_ remote OAuth did not return `200`** → Step 2B
  (local stdio, or an API key).
- **No MCP support at all** → skip to Step 4; the Agent Skill and rules file
  still work over plain REST, and tell the user their agent will call the API
  directly with `curl`.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| Cannot determine which agent you are | Unusual or embedded harness | Ask the user which coding tool they are using, then continue |
| Unsure whether a browser is available | Ambiguous environment | Ask the user: "Can you complete a sign-in in a browser on this machine right now?" |

### Step 2A: Add the MCP server (browser login)

Use this path **only if the remote-OAuth check in Step 1 returned `200`.** If it
returned 404 (or anything else), this deployment has no browser login — skip to
Step 2B; registering the endpoint here strands the user on a dead Authenticate
button.

This is the recommended path when it is available. No API key is involved: the
user signs in through their browser and the agent receives a scoped, revocable
session.

The server URL is **https://deepsieve.ai/mcp**.

**Claude Code** — run:

```bash
claude mcp add --transport http deepsieve https://deepsieve.ai/mcp
```

**Cursor** — add to `.cursor/mcp.json` in the project (create it if absent),
merging with any existing `mcpServers` rather than overwriting:

```json
{
  "mcpServers": {
    "deepsieve": { "url": "https://deepsieve.ai/mcp" }
  }
}
```

**VS Code / GitHub Copilot** — add to `.vscode/mcp.json`, merging with any
existing `servers`:

```json
{
  "servers": {
    "deepsieve": { "type": "http", "url": "https://deepsieve.ai/mcp" }
  }
}
```

**Codex** — add to `~/.codex/config.toml`:

```toml
[mcp_servers.deepsieve]
url = "https://deepsieve.ai/mcp"
```

**Any other agent** — consult your own documentation for registering a remote
(Streamable HTTP) MCP server, and register `https://deepsieve.ai/mcp` under the name
`deepsieve`. You MUST merge into existing MCP configuration rather than
replacing it.

**Success:** the server appears in your MCP server list (unauthenticated is
expected at this point).

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| `claude: command not found` | Not running inside Claude Code, or CLI not on PATH | Use the config-file method for your actual agent |
| A server named `deepsieve` already exists for a different origin | Another DeepSieve deployment is registered | Register this one under a distinct name (e.g. `deepsieve-2`) and tell the user which name maps to which origin |
| Config file is malformed after editing | Overwrote instead of merged | Restore the original, then merge the single new entry |
| Agent rejects the URL | Agent only supports stdio MCP servers | Use Step 2B instead |
| `does not support OAuth` / "discovery found no authorization support" / Authenticate does nothing | This deployment has no remote OAuth — you reached Step 2A despite the Step 1 check returning 404 | Remove this server (`claude mcp remove deepsieve` or delete the config entry) and use Step 2B (local stdio or API key) instead |

Then proceed to Step 3.

### Step 2B: Connect over local stdio or an API key

Use this when **either** is true:

- no human can complete a browser sign-in (CI, containers, remote shells), **or**
- this deployment has no remote OAuth (the Step 1 check returned 404), **even if a
  browser is available** — there is simply no browser flow to run here.

Either way this path authenticates with an API key (`ds_live_…`) rather than a
browser session.

**First, check whether you already have a credential:**

```bash
[ -n "$DEEPSIEVE_API_KEY" ] && echo present || echo missing
```

**If it is missing**, how you proceed depends on whether a human is with you:

- **A human is present** (the OAuth-off case in an interactive session): ask them
  to create an **Agent** key at https://deepsieve.ai/settings/api-keys (runs research and
  reads results; cannot change schema or billing) and put it in the environment as
  `DEEPSIEVE_API_KEY` — in their shell or a git-ignored `.env`. You MUST NOT ask
  them to paste it into this chat, and you must never mint a key yourself. Once it
  is set, re-run this step.
- **No human is present** (CI / headless): you cannot proceed on this branch and
  MUST NOT work around it. Stop and report exactly this, then skip to Step 4:

> "I can't connect DeepSieve here: this environment has no browser and no
> `DEEPSIEVE_API_KEY`. Someone with access needs to create a key at
> https://deepsieve.ai/settings/api-keys (**Agent** preset — runs research and reads
> results, cannot change schema or billing) and add it to this environment's
> secrets as `DEEPSIEVE_API_KEY`. I'll pick it up on the next run."

**If it is present**, choose the transport your environment can actually
support — check, do not assume:

```bash
command -v uvx || command -v pipx || echo "no python runner"
python3 -c 'import sys; print(sys.version_info >= (3, 11))'
```

**A. `uvx` or `pipx` available, and Python ≥ 3.11** — run the stdio MCP server:

```bash
claude mcp add deepsieve \
  --env DEEPSIEVE_API_URL=https://deepsieve.ai \
  -- uvx deepsieve-mcp
```

`DEEPSIEVE_API_URL` is REQUIRED: the stdio server defaults to
`http://localhost:8200`, so omitting it silently points at nothing. Note this
command does **not** pass the key — the server inherits `DEEPSIEVE_API_KEY` from
the environment, which is deliberate. You MUST NOT write the secret into a
config file or a command line; both get committed and logged.

For config-file agents, use `command: "uvx"`, `args: ["deepsieve-mcp"]`, and an
`env` block setting `DEEPSIEVE_API_URL` only.

**B. No Python runner, or Python < 3.11** — do NOT install one. The
Dependencies section forbids installing a global runtime, and there is no npm
distribution of the MCP server. Use plain REST instead: the API needs no
tooling, and the skill from Step 4 teaches you to drive it.

```bash
curl -s https://deepsieve.ai/v1/me -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

Tell the user you took the REST route and why.

**Success:** either the MCP server is registered (A), or the `curl` above
returns an identity (B).

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| `uvx: command not found` | `uv` not installed | Try `pipx run deepsieve-mcp`; if that is also missing, take route B — do NOT install a runtime |
| `Requires-Python >=3.11` | Interpreter too old | Take route B |
| `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | You are on 0.1.0, which predates `mcp` 2.x renaming `FastMCP` | Upgrade — **0.1.1 caps `mcp<2` and starts normally**. Pinned to 0.1.0? `uvx --with 'mcp<2' deepsieve-mcp` |
| `401` on verification | Key missing, revoked, or not visible to this process | Confirm `DEEPSIEVE_API_KEY` is exported into the environment the process inherits |
| The key was pasted into this chat | Guidance not followed | Tell them to rotate it at https://deepsieve.ai/settings/api-keys — a key in a transcript must be treated as compromised |

Then skip to Step 4 (no browser login needed).

### Step 3: Authenticate in the browser

The MCP server is registered but not yet authorized. Trigger the login so the
user can approve access.

**Claude Code:** the user runs `/mcp`, selects `deepsieve`, and chooses
**Authenticate**. A browser window opens for sign-in and consent.

**Other agents:** the first tool call against the server returns a `401` with an
OAuth challenge, and the agent prompts to sign in. Follow your own agent's
prompt. If your agent surfaces no prompt, tell the user in your own words:

> "<name> needs you to approve access in a browser. In <agent>, open its MCP or
> integrations panel, find `deepsieve`, and choose to sign in / authenticate.
> Tell me when that's done and I'll verify."

You MUST wait for the user's confirmation before continuing. Do not guess that
it worked — Step 7 is what decides.

This step requires a human. If you cannot drive it yourself, tell the user
exactly what to do and wait for their confirmation before continuing:

> "Setup is nearly done. Run `/mcp`, pick `deepsieve`, and choose
> Authenticate — a browser window will open for you to sign in. It takes about
> 30 seconds. Tell me when it's done and I'll verify the connection."

**Success:** the user confirms the browser flow completed.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| No browser opened | Headless or no default browser | Look for a URL in the output and ask the user to open it manually; if impossible, restart at Step 2B |
| Sign-in completed but tools still unavailable | The agent caches its server list per session | Ask the user to start a new session, then verify (this is expected in Claude Code) |
| "Account could not be provisioned" | First login raced a provisioning failure | Ask the user to sign in once at https://deepsieve.ai in the browser, then retry |
| User does not have an account | New user | They can sign up at https://deepsieve.ai — the same login works here |

### Step 4: Install the Agent Skill

The skill teaches you how to drive DeepSieve well: discovering the schema,
testing free before spending, and reading citations honestly.

Try the installer first:

```bash
npx skills add https://deepsieve.ai
```

**If that fails for ANY reason**, do not stop and do not report the skill as
installed. Fetch the files yourself:

```bash
curl -s https://deepsieve.ai/.well-known/skills/index.json
```

That returns the skill `name` and a `files` array of paths relative to
**https://deepsieve.ai/.well-known/skills/<name>/** — e.g.
`https://deepsieve.ai/.well-known/skills/deepsieve/SKILL.md`. Fetch each one and write it
into your own skills directory, preserving the relative paths:

| Agent | Skills directory |
|---|---|
| Claude Code | `.claude/skills/<name>/` (or `~/.claude/skills/<name>/`) |
| Cursor | `.cursor/skills/<name>/` |
| GitHub Copilot | the VS Code skills directory |
| Codex | `.codex/skills/<name>/` |

**Success:** `SKILL.md` exists in your agent's skills directory, by either
route. Say which route you used.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| `npx: command not found` | Node not installed | Use the `curl` route above; do NOT install Node without asking |
| `Installation failed` / `No well-known skills found` | Installer rejected the discovery document | Use the `curl` route above — it fetches the same files directly |
| `not a valid SKILL.md file or supported archive` | Same as above: discovery failed and it fell back to downloading the page | Use the `curl` route above |
| Skill installs but is not picked up | Agent caches skills per session | Note it in the completion message — a new session picks it up |
| Network/404 fetching the index | Wrong origin or no connectivity | Confirm https://deepsieve.ai is reachable, then retry |

### Step 5: Save the DeepSieve rules file

Rules give you durable, always-loaded guidance about this API's hazards (real
spend, customer-defined schemas, citation honesty). Identify your rules file
from this table:

| Agent | Rules file | Location |
|---|---|---|
| Claude Code | `CLAUDE.md` | Project root |
| Codex | `AGENTS.md` | Project root |
| Cursor | `.cursor/rules/*.mdc` | `.cursor/rules/` directory |
| GitHub Copilot | `.github/copilot-instructions.md` | `.github/` directory |
| Windsurf | `.windsurf/rules/*.md` | `.windsurf/rules/` directory |

Then fetch the rules content and save it to that location, creating the
directory if needed:

```bash
curl -s https://deepsieve.ai/rules/agent-rules.md
```

You MUST **append** to an existing rules file under a clear
`## DeepSieve` heading rather than overwriting it, and you MUST tell the user
which file you changed.

**Success:** the rules content is present in the agent's rules file.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| HTTP 404 or download failure | Wrong origin or no connectivity | Verify https://deepsieve.ai is reachable |
| Permission denied writing the file | No write access | Report the path; ask the user to create it or fix permissions |
| Unknown agent / no rules convention | Unsupported tool | Ask the user where their tool reads project instructions from |
| Existing rules file already has a DeepSieve section | Setup run before | Replace just that section; do not duplicate it |

### Step 6 (optional): Install the CLI

Only do this if the user works in a terminal or wants to script DeepSieve — it
is not needed for MCP to work. Ask first; do not install tooling unprompted.

```bash
uv tool install deepsieve-cli && deepsieve login
```

(`uv` from https://docs.astral.sh/uv/; `pipx install deepsieve-cli` works too.
Note the package is `deepsieve-cli` and the command is `deepsieve` — plain
`uvx deepsieve` resolves the SDK, which ships no command.) It prints a short code and opens a browser for approval, the same
device flow `gh auth login` uses.

If this deployment is not the default (production), pass the origin explicitly
and give it its own profile so it cannot collide with another:

```bash
deepsieve login --profile deepsieve --origin https://deepsieve.ai
```

**Success:** `deepsieve whoami` prints an identity.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| `uvx: command not found` | `uv` not installed | Offer `pipx install deepsieve-cli`; do not install a runtime without asking |
| Browser did not open | Headless environment | The command prints the URL and code — hand them to the user, or skip this step |
| Login times out | Nobody approved in time | Re-run; the code expires after 10 minutes |

### Step 7: Verify the connection

Confirm the setup actually works. Do not skip this, and do not claim success
without it.

**If you connected over MCP** (Step 2A or 2B): call the `get_account` tool.

**If you have no MCP** (REST only): this route never established a credential,
so first ask the user to create one at https://deepsieve.ai/settings/api-keys with the
**Agent** preset and export it as `DEEPSIEVE_API_KEY` (in their shell or a
git-ignored `.env`) — do NOT ask them to paste it to you. Then:

```bash
curl -s https://deepsieve.ai/v1/me -H "Authorization: Bearer $DEEPSIEVE_API_KEY"
```

**Success:** an identity object comes back, including `org_id`,
`workspace_schema`, `auth_kind`, and the granted `scopes`. Report the workspace
and scopes to the user in plain language.

Optionally also call `get_blueprint` (or `GET /v1/blueprints/{blueprint_id}`)
to show the user which
entities and columns their workspace defines. This is read-only and free.

**Error handling:**

| Symptom | Cause | Resolution |
|---|---|---|
| Tool not found / server not listed | The agent has not reloaded its MCP servers | Ask the user to start a new session, then verify again |
| `401` with an OAuth challenge | Browser login not completed | Return to Step 3 |
| `401` on the REST path | Key missing or revoked | Confirm `DEEPSIEVE_API_KEY`; mint a new key if needed |
| Identity returns but `workspace_schema` is null | Account has no workspace yet | Ask the user to sign in at https://deepsieve.ai once and create their first Blueprint |
| `account_not_provisioned` | Provisioning half-failed | Ask the user to sign in at https://deepsieve.ai in the browser once, then retry |

### Step 8: Report and finish

Tell the user, concisely:

1. What is now connected, and under which MCP server name.
2. Which files you changed (rules file, MCP config) — list the paths.
3. Their workspace and the scopes granted.
4. That research runs **cost credits and take 15–60 minutes**, and that
   `dry_run` runs are free for testing an integration.
5. That they should **start a new session** so the skill and rules load.

End with:

> "Setup is complete. Start a new session so the skill and rules take effect —
> then ask me to explore your DeepSieve data, or to draft a research run for
> your review before anything is spent."

If any step was skipped or unverified, state exactly which, and why.