# Connect an agent

The MCP server lives at `https://sceniq.earth/api/mcp`. It speaks the Streamable HTTP transport, statelessly: every message is one POST, there are no sessions and no server-initiated stream. Every operation of the [API reference](https://developers.sceniq.earth/reference.md) except the photo uploads is one tool.

When an agent connects, the server hands it short instructions: the non-negotiables (never invent facts, photos only from the creator, nothing goes live unless the creator says so) and the workflow. The full playbook is the [authoring skill](https://sceniq.earth/developers/skill.md); install it where your agent reads skills.

## Claude Code

Adds the Sceniq MCP server to Claude Code for the current project (drop --scope project for just this machine). Then install the skill so Claude follows the authoring rules.

```bash
claude mcp add --transport http sceniq https://sceniq.earth/api/mcp \
  --header "Authorization: Bearer sk_sceniq_YOUR_KEY"

mkdir -p .claude/skills/sceniq-guide-authoring
curl -fsSL https://sceniq.earth/developers/skill.md -o .claude/skills/sceniq-guide-authoring/SKILL.md
```

## Claude Desktop

Claude Desktop connectors do not pass custom headers yet, so the open-source mcp-remote bridge supplies the key. Add this to claude_desktop_config.json.

```json
{
  "mcpServers": {
    "sceniq": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://sceniq.earth/api/mcp",
        "--header",
        "Authorization: Bearer ${SCENIQ_API_KEY}"
      ],
      "env": {
        "SCENIQ_API_KEY": "sk_sceniq_YOUR_KEY"
      }
    }
  }
}
```

## Cursor

Add to .cursor/mcp.json in your project (or the global ~/.cursor/mcp.json).

```json
{
  "mcpServers": {
    "sceniq": {
      "url": "https://sceniq.earth/api/mcp",
      "headers": {
        "Authorization": "Bearer sk_sceniq_YOUR_KEY"
      }
    }
  }
}
```

## Codex CLI

Add to ~/.codex/config.toml. Codex reads the key from the environment variable named in bearer_token_env_var.

```toml
[mcp_servers.sceniq]
url = "https://sceniq.earth/api/mcp"
bearer_token_env_var = "SCENIQ_API_KEY"

# then: export SCENIQ_API_KEY="sk_sceniq_YOUR_KEY"
```

## Check the connection

Ask the agent to call `whoami`. It answers with the creator, the key's scopes and the limits. If the agent reports `invalid_api_key`, the key was revoked or mistyped; make a new one in the studio.

## Without an MCP client

Every tool is also a REST endpoint with the same input, and the [OpenAPI document](https://sceniq.earth/api/v1/openapi.json) describes all of them. Any HTTP client works.

## Protocol details

- Protocol versions 2025-06-18, 2025-03-26 and 2024-11-05; the server answers with the one the client asks for, or the newest.
- `initialize` returns the instructions and `capabilities.tools`. `tools/list` returns every tool with its title, annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`) and input schema.
- `tools/call` returns the result as text and as `structuredContent`. A refused call is a tool result with `isError: true` and the error code in the text, never a protocol error.
- GET and DELETE answer 405. Authentication failures answer 401 with `WWW-Authenticate: Bearer realm="sceniq"`.