diff --git a/docs/changelog/overview.mdx b/docs/changelog/overview.mdx index c0055fdc..c2d3c541 100644 --- a/docs/changelog/overview.mdx +++ b/docs/changelog/overview.mdx @@ -13,6 +13,8 @@ Release notes for the Flare Platform can be found on the [product documentation + Released the [Flare API MCP server (beta) ](/sdk/api-mcp). + Added the `urls` value to the `include` parameter in the [ASTP Search Credentials Endpoint ](/api-reference/astp/endpoints/post-credentials-search). Added the [ASTP List URLs by Credential Hash Endpoint ](/api-reference/astp/endpoints/post-urls-by-credential-hash) to list the URLs where a leaked credential was seen. @@ -99,7 +101,7 @@ Release notes for the Flare Platform can be found on the [product documentation Released the - [Flare API Documentation MCP Server ](/sdk/mcp). + [Flare API Documentation MCP Server ](/sdk/docs-mcp). This is useful for developers building Flare API automations with AI-powered integrated development environments (IDE). diff --git a/docs/docs.json b/docs/docs.json index 3bbd94ec..72a72c4e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -34,7 +34,8 @@ "sdk/python", "sdk/go", "sdk/cli", - "sdk/mcp" + "sdk/api-mcp", + "sdk/docs-mcp" ] }, { diff --git a/docs/introduction/getting-started.mdx b/docs/introduction/getting-started.mdx index c36910b8..3700d69d 100644 --- a/docs/introduction/getting-started.mdx +++ b/docs/introduction/getting-started.mdx @@ -35,15 +35,31 @@ The Flare API can be used to access Flare's search capabilities, configure monit The Go SDK exposes a small `net/http.Client` wrapper that automatically manages authentication. - - - Flare provides a Command Line Interface (CLI) utility - that can be used to interact with the Flare API. + + + +## CLI + + + + + Interact with the Flare API from your terminal. + + + + +## MCP + + + + + Connect any MCP-capable client to Flare's search + and platform APIs. - - Flare provides a Model Context Protocol (MCP) server - that can be used to ask questions about the Flare API. + + Ask questions about the Flare API and its documentation from any + MCP-capable client. diff --git a/docs/sdk/api-mcp.mdx b/docs/sdk/api-mcp.mdx index dff999c2..c97051f2 100644 --- a/docs/sdk/api-mcp.mdx +++ b/docs/sdk/api-mcp.mdx @@ -4,7 +4,6 @@ title: "API MCP (beta)" The Flare API MCP server is still in beta and is subject to change. - {/* TODO Specify beta quota adjustements */} Flare provides a @@ -12,38 +11,44 @@ Flare provides a exposes Flare's search and platform APIs to any MCP-capable client. It lets agents query Flare's threat-intel dataset, inspect a tenant's monitored events, look up event-type schemas, and read the current user's profile — -without writing any code against the REST API directly. +without writing any code against the REST API. For a documentation-only companion server (search across the Flare API docs themselves), see the -[Documentation MCP ](/sdk/mcp). +[Documentation MCP ](/sdk/docs-mcp). ## Available Tools | Tool | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| `search_search` | Global Search — execute a Lucene query against the entire Flare threat-intel dataset. | +| `search_global` | Global Search — execute a Lucene query against the entire Flare threat-intel dataset. | | `search_tenant` | Tenant Search — execute a Lucene query scoped to events matching the caller's monitored identifiers. | -| `validate_search_query` | Validate that a Lucene query complies with Flare's search rules before running it. Useful when composing or debugging a query. | -| `get_event_type` | Return the documentation and searchable field list for a given event type (e.g. `chat_message`, `forum_post`, `stealer_log`). | +| `search_validate_search_query` | Validate that a Lucene query complies with Flare's search rules before running it. Useful when composing or debugging a query. | +| `events_get_event_type` | Return the documentation and searchable field list for a given event type (e.g. `chat_message`, `forum_post`, `stealer_log`). | | `profile_get` | Return the current user's profile, including tenants, permissions, feature flags, and default tenant id. | + + + `search_global` requires the Global Search permission on the target + tenant. + + ### Search Parameters -The `search_search` (Global) and `search_tenant` (Tenant) tools accept the +The `search_global` and `search_tenant` tools accept the same parameters: - Lucene query string. + Lucene query. - Time window to restrict results to. Either a preset (`last_24h`, `last_7d`, - `last_1m`, …) or a `{ begin_at, end_at }` object with ISO-8601 datetimes. + Time window to restrict results to. Either a preset (`last_24h`, `last_2d`, `last_7d`, + `last_1m`, `last_3m`, `last_6m`, `all`) or a `{ begin_at, end_at }` object with ISO-8601 datetimes. - List of event types to scope the search. + List of event types to scope the search. Defaults to all event types. @@ -68,35 +73,47 @@ The MCP server is available at the following URL: - `https://api.flare.io/mcp` -For a copy-pasteable example that wires everything below into a client, see +To connect an MCP client to the server, see [Client Setup](#client-setup). -#### Authentication +### Authentication Every MCP request must include a Flare API key in the `Authorization` header. Follow the [Authentication Guide ](/concepts/authentication) to generate one. -#### Targeting a specific tenant +### Targeting a specific tenant Requests default to your account's default tenant. To scope MCP tool calls to a specific tenant, set the `X-Flare-Tenant-Id` header on the MCP -connection to the target tenant id. You can find your tenant ids on the -[Profile page](https://app.flare.io/#/profile) under the "Tenants" section +connection to the target tenant id. You can find your tenant ids via the `profile_get` MCP tool, or on the [Profile page](https://app.flare.io/#/profile) under the "Tenants" section (also documented in the -[Authentication Guide ](/concepts/authentication#finding-tenant-ids)). +[Authentication Guide ](/concepts/authentication#finding-tenant-ids)). ## Client Setup + +The `X-Flare-Tenant-Id` header is optional: omitting it uses your default tenant. + + ### Claude Code -[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) reads -MCP servers from an `.mcp.json` file at the root of your project. Create the -file with the snippet below, replacing `` with a Flare API key -obtained from the +The quickest way to add the server to a project's config is through the +[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) CLI: + +```bash +claude mcp add flare --transport http https://api.flare.io/mcp \ + --scope project \ + --header "Authorization: " \ + --header "X-Flare-Tenant-Id: " +``` +The Flare API key is obtained from the [Authentication Guide ](/concepts/authentication). +Alternatively, you may create an +`.mcp.json` file at the root of your project and restart Claude Code once the file is in place: + ```json .mcp.json { "mcpServers": { @@ -112,7 +129,7 @@ obtained from the } ``` -Restart Claude Code once the file is in place. The Flare tools will appear +The Flare tools will appear under the `flare` server in the `/mcp` command output, and Claude will call them automatically when your prompts match their descriptions. @@ -125,25 +142,58 @@ them automatically when your prompts match their descriptions. ### Claude Desktop -Claude Desktop can connect to the Flare MCP server as a remote **Custom -Connector**. Follow the official walkthrough: - -- [Getting started with custom connectors using remote MCP](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp#h_3d1a65aded) +Claude Desktop's configuration file only supports local (stdio) servers, so the connection goes through the `mcp-remote` bridge via `npx` (requires Node.js). +The configuration file is located at: -When prompted for the server URL, use `https://api.flare.io/mcp`, and set -the `Authorization` header to your Flare API key. +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` -### Other Clients +The file is also reachable through **Settings → Developer → Edit Config**. -- **Cursor** — - [Using `mcp.json`](https://cursor.com/docs/mcp). - The same JSON shape shown above for Claude Code applies. +```json claude_desktop_config.json +{ + "mcpServers": { + "flare": { + "command": "npx", + "args": [ + "-y", + "mcp-remote", + "https://api.flare.io/mcp", + "--header", + "Authorization:", + "--header", + "X-Flare-Tenant-Id:" + ] + } + } +} +``` +Once the change is in place, you should fully quit and relaunch Claude Desktop. + +### Cursor + The server can be added to the `.cursor/mcp.json` in your project (or + `~/.cursor/mcp.json` to make it available in all projects). + ```json .cursor/mcp.json + { + "mcpServers": { + "flare": { + "url": "https://api.flare.io/mcp", + "headers": { + "Authorization": "", + "X-Flare-Tenant-Id": "" + } + } + } + } + ``` + Cursor picks up the change automatically: check **Settings → MCP** to confirm the MCP server is connected. + See [Cursor's MCP docs](https://cursor.com/docs/mcp) for details. ## Quotas & Rate Limits -- Calls to `search` (Global Search) consume the tenant's monthly Global +- Calls to `search_global` (Global Search) consume the tenant's monthly Global Search quota. See [Rate Limits and Quotas ](/concepts/rate-limits-and-quotas). -- `tenant`, `validate_search_query`, `get_event_type`, and `get` (profile) do +- Calls to other tools do not consume the Global Search quota. - Standard API rate limits apply to all tools. diff --git a/docs/sdk/mcp.mdx b/docs/sdk/docs-mcp.mdx similarity index 96% rename from docs/sdk/mcp.mdx rename to docs/sdk/docs-mcp.mdx index 7a58f4ea..ef7492b1 100644 --- a/docs/sdk/mcp.mdx +++ b/docs/sdk/docs-mcp.mdx @@ -1,5 +1,5 @@ --- -title: "MCP (beta)" +title: "Documentation MCP (beta)" ---