# Connect via MCP

Point any MCP-capable AI client at the hosted MCP server and drive Indexhog over OAuth — no token to paste.

Indexhog runs a hosted, remote **Model Context Protocol (MCP)** server. Point an MCP-capable
client at one URL, sign in once, and your agent can manage projects, organizations, and billing
through the same API the dashboard uses. The server is an OAuth 2.1 resource server — you authorize
in the browser, so there is no API key to copy or store.

> **Info:** **You need:** an account and an MCP-capable client (Claude Desktop, Claude Code, Cursor, VS Code,
> or anything that speaks MCP over HTTP). The MCP endpoint is `https://mcp.indexhog.com`.

## The server URL

Add this server to your client. On first use the client opens a browser window for you to sign in
and authorize — the OAuth 2.1 + PKCE handshake (discovery, dynamic registration, token exchange)
happens automatically.

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

> **Warning:** **MCP does not accept `tkn_` personal access tokens.** PATs are for the REST API only (sent on the
> `X-Api-Key` header). The MCP server authenticates with an OAuth access token that the client
> obtains for you. If you put a PAT in the `Authorization` header, the server returns `401`.

## Agent discovery

Inspect the REST surface that backs the MCP tools:

- [OpenAPI 3.1 specification](https://api.indexhog.com/agents/openapi.json) — Machine-readable contract for API clients and code generators.
- [Capabilities manifest](https://api.indexhog.com/agents/capabilities.json) — Agent-oriented inventory of endpoints, scopes, authentication, and features.

## Add the server to your client

### Claude (Desktop & claude.ai)

Open **Settings → Connectors → Add custom connector**, give it a name, and paste the server URL:

```text
https://mcp.indexhog.com
```

Claude prompts you to sign in and authorize on first use. The tools then appear in the connector
list.

### Claude Code

Add the server from the CLI as a streamable-HTTP transport:

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

Run `/mcp` inside Claude Code to trigger the browser sign-in, then confirm the server shows as
connected.

### Cursor

Add it to your project's `.cursor/mcp.json` (or the global `~/.cursor/mcp.json`):

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

Open **Settings → MCP**, confirm the server is listed, and complete the sign-in when prompted.

### VS Code

Register the server with the CLI:

```bash
code --add-mcp '{"name":"indexhog","url":"https://mcp.indexhog.com"}'
```

Or add it to `.vscode/mcp.json` using the same shape as the Cursor example above.

### Other clients (mcp-remote fallback)

Clients that only speak stdio can bridge to the remote server with `mcp-remote`:

```json
{
"mcpServers": {
  "indexhog": {
    "command": "npx",
    "args": ["-y", "mcp-remote", "https://mcp.indexhog.com"]
  }
}
}
```

## Authentication & sessions

The server implements **OAuth 2.1 + PKCE** with dynamic client registration (RFC 7591) and exposes
protected-resource metadata (RFC 9728), so compliant clients discover everything they need from the
URL alone.

- **Discovery:** `GET https://mcp.indexhog.com/.well-known/oauth-protected-resource` returns the
  authorization server (`https://api.indexhog.com/api/auth`).
- **Token:** the client runs the OAuth flow in your browser and sends `Authorization: Bearer <jwt>`
  on every call.
- **Sessions are short-lived.** A `401` always carries a `WWW-Authenticate: Bearer …` header pointing
  at the resource-metadata URL, so clients re-authorize automatically.
- **Request bodies are capped at 1 MB.**

## Available tools

The MCP server exposes the agent-callable subset of the external contract as tools, grouped below. The live, always-current
list is whatever your client's `tools/list` returns — treat that as the source of truth and follow
the linked references for full arguments and responses.

| Group                                                                                                                                        | Reference                                          |
| -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Projects & inventory (`list_user_projects`, `create_project`, `list_project_urls`, `get_project_stats`)                                      | [Projects](/docs/api-reference/projects)           |
| Verification (`get_project_verification`, `verify_project_dns`)                                                                              | [Projects](/docs/api-reference/projects)           |
| Issues & engines (`list_project_issues`, `connect_project_bing`, `get_project_gsc_o_auth_url`)                                               | [Projects](/docs/api-reference/projects)           |
| Organizations & members (`list_user_organizations`, `create_organization`, `create_organization_invites`, `update_organization_member_role`) | [Organizations](/docs/api-reference/organizations) |
| SSO & MFA (`get_organization_sso_config`, `update_organization_sso_config`, `update_organization_mfa_settings`)                              | [Enterprise SSO](/docs/get-started/enterprise-sso) |
| Billing (`create_checkout_session`, `get_billing_settings`)                                                                                  | [Payments](/docs/api-reference/payments)           |
| User & account (`get_current_user`, `export_user_data`)                                                                                      | [User](/docs/api-reference/user)                   |

API-key management and other auth-tier operations remain REST/session-only.
External documentation does not automatically make an operation an MCP tool.

> **Tip:** **Set organization context first.** Most tools are scoped to an organization. Call
> `get_current_user`, then `list_user_organizations` to pick the target org, before running
> org-scoped tools — skipping this is the most common first-run error
> (`TENANT_CONTEXT_MISSING`).

## Use the product skill

The **product skill** packages everything an agent needs to drive Indexhog — connection rules,
org-context flow, pagination and response-envelope conventions, tool disambiguation, and
step-by-step workflows. Install it alongside the MCP server for far fewer first-run mistakes.

- **Download the bundle:** [product-skill.zip](/skill/product-skill.zip)
- **View the source:** [SKILL.md](/skill/SKILL.md) · [workflows.md](/skill/references/workflows.md)

To install in **Claude Code**, unzip into your skills directory:

```bash
mkdir -p ~/.claude/skills
unzip product-skill.zip -d ~/.claude/skills
# → ~/.claude/skills/product/SKILL.md
```

For **claude.ai**, upload the unchanged `product-skill.zip` in **Settings → Capabilities → Skills**.

## Troubleshooting

| Symptom                                              | Cause                                                        | Fix                                                                    |
| ---------------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `401 Unauthorized`                                   | No token, expired session, or a `tkn_` PAT on the MCP server | Re-run the client's sign-in; MCP needs an OAuth token, not a PAT       |
| `TENANT_CONTEXT_MISSING` / `NOT_ORGANIZATION_MEMBER` | Called an org-scoped tool without choosing an org            | Run `list_user_organizations` and pass that org's id                   |
| `429 Too Many Requests`                              | Rate limit hit                                               | Honor `Retry-After` before retrying                                    |
| Client can't connect                                 | Wrong URL or stdio-only client                               | Use `https://mcp.indexhog.com`; bridge stdio clients with `mcp-remote` |

## Best Practices

- **Let the client handle OAuth:** Never paste tokens into MCP config — the browser sign-in is the supported path and keeps credentials out of files.
- **Pick the org once per session:** Resolve the organization id early and reuse it; most failures trace back to missing org context.
- **Prefer MCP for agents, REST for CI:** Interactive agents authorize via OAuth; headless automation uses a scoped `tkn_` PAT on the REST API.
- **Ship the skill with the server:** The skill encodes the conventions (`offset`/`limit` pagination, the response envelope) that agents otherwise learn by failing.

## Next Steps

1. **Authenticate the REST way too:** Follow [Quick Start](/docs/get-started/quick-start) to issue a PAT for headless automation.
2. **Choose scopes intentionally:** Review [Scopes & Permissions](/docs/get-started/scopes) before issuing tokens.
3. **Browse the surface:** Start at the [Projects reference](/docs/api-reference/projects) to see what the tools wrap.