Skip to main content
Glama
Flux MCP

Flux MCP

Official
by Flux-Search

Flux MCP

Flux for Claude, Codex, Cursor and any other MCP client. It gives your assistant four tools:

  • search searches the web and returns ranked results. Pages Flux reads come back with the passages that answer the query.

  • lineage reads a document or a web page and returns only the passages that answer your questions. People, places, organisations and dates are written into each passage where it needs them, such as the name behind "she" or the exact month behind "last April".

  • fetch returns one web page whole, as clean markdown with its title and published date.

  • account shows your balance. It is free.

The Claude Code plugin also installs a skill that teaches Claude when to use each tool and how to report what comes back.

What you need

  • A Flux API key. It starts with user_sk_ (personal) or org_sk_ (workspace). Create one at app.fluxsearch.io/keys.

  • Node.js 18 or newer, for every client except Claude Desktop. Check with node --version, and install it from nodejs.org if that fails.

Nothing is cloned or built. Each install below is one step, and starting a new session loads it.

Related MCP server: Devin Search MCP

Install

Claude Code

/plugin marketplace add Flux-Search/flux-MCP
/plugin install flux@flux-search

This installs the tools and the skill. Claude Code asks for your Flux API key and keeps it in your system's credential store, not in a settings file. Start a new session afterwards. /plugin updates it later.

For the tools without the skill:

claude mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP

Claude Desktop

Download flux.mcpb from the latest release and open it, or drag it onto Settings, Extensions. Claude Desktop asks for your Flux API key and runs the server itself, so Node.js is not needed.

Codex CLI and IDE

codex mcp add flux --env FLUX_API_KEY=user_sk_... -- npx -y github:Flux-Search/flux-MCP

To keep the key out of your shell history in Windows PowerShell:

$key = Read-Host "Flux API key"
codex mcp add flux --env "FLUX_API_KEY=$key" -- npx -y github:Flux-Search/flux-MCP
Remove-Variable key

The skill for Codex:

npx skills add https://github.com/Flux-Search/flux-MCP/tree/main/codex --skill flux-codex --agent codex --global

Check it with codex mcp get flux, or /mcp inside Codex. Codex lists the server as Auth unsupported, which is expected: the key is passed as an environment variable, not through OAuth. --env saves the key in Codex's local config, so do not commit or share that file.

Codex Cloud

Add this to the project's .codex/config.toml, and store FLUX_API_KEY as a Cloud environment secret. Never put the key itself in the file.

[mcp_servers.flux]
command = "npx"
args = ["-y", "github:Flux-Search/flux-MCP"]
env_vars = ["FLUX_API_KEY"]
tool_timeout_sec = 150
startup_timeout_sec = 30

Cursor and other MCP clients

Any client that starts a server with a command works the same way. For Cursor, add this under mcpServers in ~/.cursor/mcp.json:

{
  "flux": {
    "command": "npx",
    "args": ["-y", "github:Flux-Search/flux-MCP"],
    "env": { "FLUX_API_KEY": "user_sk_..." }
  }
}

Updating

The Claude Code plugin updates through /plugin. Claude Desktop updates when you install a newer flux.mcpb. npx -y github:Flux-Search/flux-MCP fetches the latest version each time your client starts it; add a tag such as #v0.4.0 to the end to pin one.

Using it

Ask in plain language:

  • "Search for the latest UK inflation figure and tell me where it comes from."

  • "Read https://example.com/article and tell me why prices rose."

  • "Use lineage on this report and list everyone it mentions", then paste the text.

  • "What's my Flux balance?"

examples/ has three short articles with prompts to try.

lineage

Send text or url, and your questions in queries.

Argument

text

The document, up to 60,000 characters.

url

A page for Flux to fetch and read. If the site refuses, you get an error and are not charged.

queries

Up to 10 questions. Each is a full pass over the document and is billed as one. Leave it out to get every passage, which is longer than the input.

query

One question. The same as queries with one entry.

published

When a pasted text was published, as an ISO date. It lets "last April" resolve to the right year.

documents

Up to 100 documents in one call, each with its own text or url, and optionally its own queries and published. Documents that cannot be read are listed and not charged.

Argument

query

What to search for. Required.

max_results

1 to 20, default 10.

enrich

How many results Flux reads for passages. The default is all of them. 0 returns results without reading any pages, which is fastest.

allowed_domains

Only return pages from these sites, up to 10.

blocked_domains

Never return pages from these sites, up to 20.

fetch

Argument

url

A public http or https address. Required.

Pages longer than 100,000 characters are cut, with a note saying so.

account

No arguments. Returns your balance and roughly how many tokens of Lineage input it covers.

What comes back

Passages, each with a relevance score. The text is the passage with its context written in, ready to paste into another prompt:

She [Jane Doe] said the ministry raised fuel prices on Tuesday [Jul 28, 2026].

Under each passage, what it mentions, such as person: She -> Jane Doe. An arrow means a vague mention was matched to a full name or a date.

Search results also carry a direct answer when the index has one, related searches, and a note for any page Flux could not read.

Every call ends with its cost in dollars.

Pricing

Lineage is billed by the tokens it reads, once per question: five questions over one document are five passes. Search and fetch are a flat price each. The account tool is free, and errors are never charged. Current prices are at fluxsearch.io/pricing.

Good to know

  • Read any WARNING line. Lineage warns when only the start of a long document was read. Search warns when the index ran in a reduced mode.

  • A document can be up to 60,000 characters, about 9,000 words. Split longer ones, or use documents.

  • A 402 error means the balance is too low. Add credit at app.fluxsearch.io.

Troubleshooting

What you see

What to do

The tools do not appear

Start a new session, then check claude mcp list or codex mcp get flux.

FLUX_API_KEY is not set

The server started without a key. Register it again with --env FLUX_API_KEY=..., or add the Cloud secret.

Auth unsupported in Codex

Expected. See the Codex section.

unauthorized

The key is wrong or has been revoked. It starts with user_sk_ or org_sk_.

insufficient_credits

The balance is too low. Add credit and try again.

rate_limited

Too many calls. Wait for the number of seconds in the message.

fetch_failed

The site refused automated access or the page had no text. Nothing was charged.

It times out

Try again, or raise FLUX_TIMEOUT_MS.

Settings

Variable

Default

FLUX_API_KEY

none

Required.

FLUX_API_BASE_URL

https://fluxsearch.io

Only set this to use a different deployment.

FLUX_TIMEOUT_MS

120000

How long to wait for an answer, in milliseconds.

The API behind it

The tools call the Flux REST API. To call it directly, see the API reference and the getting started guide. The API also has OpenAI-compatible endpoints, so the OpenAI SDK works with a changed base URL.

Maintainers

bundle/index.js is committed so that installing needs no toolchain, and CI fails if it does not match the source. The source is src/index.ts (the server) and src/flux.ts (request building, formatting and error text). After changing them, rebuild and commit the bundle:

npm install
npm test
npm run bundle

Bump the version in package.json, src/index.ts, .claude-plugin/plugin.json and manifest.json together. Pushing a v* tag runs the tests, builds flux.mcpb and attaches it to a GitHub release.

npm run build only type-checks. The API is described by fluxsearch.io/api-reference/openapi.json.

License

MIT. See LICENSE.

Available Tools

4 tools
accountA
Read-only

Show the Flux account balance, and roughly how many tokens of Lineage input it covers. Free. Check it before a large job.

Inputs: no named parameters.

fetchA
Read-only

Fetch one web page and return it whole as clean markdown, with its title and published date. Use it when you need the full page; use lineage when you only need the parts that answer a question, which is cheaper on long pages.

Inputs: url (required).

lineageA
Read-only

Read a document or a web page and return only the passages that answer your questions, with the people, places, organisations and dates written in where a passage needs them (the name behind 'she', an exact date for 'last April'). Send text or a url, and the questions in queries. Each question is a separate pass and is billed as one. Without queries, every passage comes back, which is larger than the input. Use it to turn a long source into grounded context.

Inputs: url, text, query, queries, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation4/5

    The tools have mostly distinct purposes: account checks billing, search finds sources, fetch returns a full page, and lineage extracts targeted passages. The main overlap is between fetch, lineage, and search because all can return web content, but the descriptions explicitly clarify when to use each.

    Naming Consistency4/5

    All names are single lowercase words, which gives a consistent surface style. However, the set mixes nouns (account, lineage) with verbs (fetch, search), so it is readable but not a strict verb_noun convention.

    Tool Count5/5

    Four tools is well-scoped for this server: billing, search, full-page retrieval, and grounded extraction. Each tool has a clear role and earns its place without bloat.

    Completeness4/5

    The core workflow is covered: check balance, search the web, fetch a page, and extract answers from a document or URL. Minor gaps exist around batch reading or managing multiple sources, but agents can work around them by making repeated calls.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Gives MCP-capable agents live web access: search the web, scrape pages into Markdown (including JavaScript-heavy and bot-protected sites), and extract named fields as JSON, with job polling, token-aware content offloading, and built-in research guidance. Ships as a self-hostable stdio or HTTP service with spend caps and per-request key support.
      7
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI coding assistants to perform real-time web searches for technical documentation and deep-fetch web pages, returning clean structured results. It supports integration with MCP clients such as Cursor, Claude, and CodeBuddy.
      3
      108 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to read public web content as clean Markdown, search a private library of previously read documents, and access these tools via MCP, REST API, CLI, and WebMCP.
      23
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to search the web with clean page text, crawl websites into Markdown, extract articles and structured data, and monitor Google News and press releases for LLM context and RAG pipelines. It works with MCP clients and uses the user's own Apify API token for pay-per-result data retrieval.
      6
      MIT