Audit Kagi Session2API MCP Before Sharing Account Access

Kagi Session2API MCP is a strong rescue candidate, but not for the reason the old title suggested. The weak version says: use a Kagi session token and skip API setup. The useful version says: if a Claude Code agent can search and summarize through your Kagi account, you have created a powerful local search tool and a serious account boundary at the same time.

The project is honest about that boundary. Its README says it uses session tokens rather than Kagi's official API key, warns that this may violate Kagi's Terms of Service, and says the token should be treated like a password. Kagi's own docs reinforce the point: a Session Link automatically logs into an existing Kagi session, must not be shared, and can be invalidated by signing out. That is enough substance for a proper magazine article: not a setup cheer, but a field guide for when this MCP belongs on one developer's machine and when a team should use Kagi's official API or official MCP instead.

What the MCP Actually Exposes

server.py defines a FastMCP server with two tools. kagi_search_fetch takes one or more search queries and returns formatted search results. kagi_summarizer takes a URL and returns a summary or takeaway list. For a Claude Code workflow, that means an agent can search the web and summarize a target page without the user leaving the terminal.

The implementation path is specific. client.py creates an httpx.AsyncClient per session token, sets the token as a kagi_session cookie, spoofs Firefox headers, enables HTTP/2, and fetches Kagi's /html/search endpoint. parser.py then converts server-rendered Kagi HTML into API-like result objects using selector fallbacks such as .search-result, .sri, and [data-og-url]. The formatter emits numbered results so the agent can refer back to result 3 or result 7 in later reasoning.

That is useful for agent work because search results become tool output instead of pasted browser text. It is also fragile because HTML selectors and internal endpoints are not a stable public contract.

The Session Token Is the Product Boundary

The article should not hide the credential model. The project supports KAGI_SESSION_TOKEN, KAGI_SESSION_TOKENS, and a TOML config file under ~/.config/kagi-session2api-mcp/config.toml. The config loader gives env vars priority, validates that tokens are present and long enough, and warns if a config file is readable by group or others.

A personal setup should keep the secret outside the repo:

# ~/.config/kagi-session2api-mcp/config.toml
[kagi]
session_tokens = ["PASTE_ONE_TOKEN_HERE"]
summarizer_engine = "cecil"

[client]
timeout = 30
max_retries = 2

Then lock it down:

chmod 600 ~/.config/kagi-session2api-mcp/config.toml

Do not put a real Kagi session token in .mcp.json, .claude/settings.json, a shared Skill, a project README, or a screenshot. A project MCP config can point at the command, but the token itself belongs in user or machine-local secret handling.

Install It Like a Reversible Experiment

The safe path is to make the experiment easy to remove. Install with uvx, keep the token in a local config file, and keep the MCP entry in user-local Claude Code settings unless you have a reason to share it.

mkdir -p ~/.config/kagi-session2api-mcp
chmod 700 ~/.config/kagi-session2api-mcp
$EDITOR ~/.config/kagi-session2api-mcp/config.toml
chmod 600 ~/.config/kagi-session2api-mcp/config.toml
uvx kagi-session2api-mcp --help

Then wire Claude Code to the config path, not to the token value:

{
  "mcpServers": {
    "kagi-session": {
      "command": "uvx",
      "args": ["kagi-session2api-mcp"],
      "env": {
        "KAGI_SESSION_CONFIG": "/Users/you/.config/kagi-session2api-mcp/config.toml"
      }
    }
  }
}

Verify the server exists before using it:

claude mcp list

If the trial goes wrong, remove the MCP entry, sign out of the Kagi session that generated the link, and rotate the token by signing in again. Kagi's private-session docs state that a Session Link is tied to the session it came from and can be invalidated by signing out.

Run a One-Session Trial

A practical trial should leave evidence. Use a disposable branch or scratch repo, then record what the agent did before deciding whether the MCP belongs in your daily setup.

git switch -c trial/kagi-session-mcp
mkdir -p ~/.config/kagi-session2api-mcp
chmod 700 ~/.config/kagi-session2api-mcp
$EDITOR ~/.config/kagi-session2api-mcp/config.toml
chmod 600 ~/.config/kagi-session2api-mcp/config.toml
uvx kagi-session2api-mcp --help
claude mcp list

Then run one public query and one teardown check:

Use kagi_search_fetch to find official Kagi MCP documentation with limit 3.
Return only titles, URLs, and the tool name used.
Do not call kagi_summarizer yet.

rg -n "KAGI_SESSION|kagi-session|session_tokens" . ~/.claude 2>/dev/null

The expected evidence is simple: the MCP appears in claude mcp list, the search call returns public URLs, the transcript names kagi_search_fetch, and no token string appears in repo files. If that evidence is missing, do not continue. If it passes, try one public summarizer URL and record whether the result is useful enough to justify the credential risk.

A Safer Local Claude Code Setup

For a single developer who accepts the risk, the MCP should be treated as a read-only research helper. Start with a public documentation query and a low result limit:

Use kagi_search_fetch to search for "Claude Code MCP server docs" with limit 3.
Do not summarize or open any private URL.
Return result titles and URLs only.

Then inspect the transcript. Does the tool output contain only search results, or does it bring back a page that could inject instructions into the agent? Does the agent cite results instead of treating snippets as ground truth? Does the summarizer call touch a private URL or internal document? If any answer is unclear, remove the server and use the browser or official API path instead.

The setup is small. The review is the important part.

Three Jobs Where It Actually Helps

The project becomes interesting only when the agent job is specific enough to audit. The first good job is source reconnaissance before editing a Skill or AGENTS.md file. Claude Code can search for public docs, return candidate URLs, and let the user decide which sources belong in the change. The MCP is helpful there because it turns search into a small tool call, not a browser detour.

The second good job is dependency triage. If a local MCP server fails after a package update, Claude Code can search error text, release notes, and upstream issue titles while staying inside the terminal session. The rule is that the search result is a lead, not evidence. The agent still has to open the real source, quote the exact behavior, and run the local test.

The third good job is pre-research for a manual article rescue like this one. The agent can collect public pages about Kagi APIs, MCP transport, and token handling before the writer decides the angle. The boundary is strict: no private repo URLs, no customer pages, no internal docs, and no unattended summarizer calls. If the workflow needs any of those, Session2API is the wrong tool.

A Decision Test Before Sharing It

Before this enters a reusable Codex setup, ask five questions. Can the session token be rotated without touching the repo? Can every request be explained from the transcript? Would the same workflow be acceptable if a teammate ran it from their account? Is there a documented fallback when Kagi HTML parsing changes? Would the workflow still be worth running if it used the official API and paid credits?

A personal experiment can survive a no on the last question. A team tool cannot survive a no on the first four. That is the difference between an MCP that helps one developer think and a credential pattern that quietly spreads account access through a project.

This is also why the article should not recommend committing a ready-made .mcp.json. The reusable asset is the decision rule: session-token MCPs belong in user-local experiments; official API keys belong in shared infrastructure.

Where the Official Kagi API Is Different

Kagi's official Search API uses an Authorization: Bot $TOKEN header. The API portal exposes API keys, product access settings, usage reporting, billing, prepaid credit, spending limits, and optional IP restrictions. Kagi's API portal also notes an official Kagi MCP server for the newer Search and Extract APIs.

Those controls matter. An API key can be scoped and tracked in a way a session token cannot. Billing and usage reports tell a team which service made requests. IP restrictions can reduce blast radius. Product-level access can keep a search credential from becoming a broad account session.

Use this split before adoption:

Use Session2API when:
- one developer is testing Kagi search inside a local Claude Code session
- the token stays in a user-local config file
- failure means removing one MCP entry and signing out of one Kagi session

Use the official API or official MCP when:
- more than one person will rely on the search tool
- the agent may run unattended
- usage should appear in billing, limits, or audit records
- summaries or extraction become part of a product or publishing pipeline

So the adoption split is clear. Use the official API or official MCP for shared infrastructure, company repos, production assistants, or anything that may run unattended. Use Session2API only as a personal experiment when the goal is to test whether Kagi search improves an agent loop before paying the integration cost.

Migration Path If the Trial Works

The right outcome of a successful Session2API trial is not to share the session token. It is to prove that Kagi search belongs in the agent loop, then move the shared version to a supported credential model.

Step one: keep the transcript from the one-session trial and mark the exact requests that were useful. Step two: create or choose an official Kagi API credential through the API portal. Step three: run a direct API smoke test outside the agent:

curl -H "Authorization: Bot $KAGI_API_TOKEN" \
  "https://kagi.com/api/v1/search?q=claude+code+mcp"

Step four: decide whether the team needs raw API access, the official Kagi MCP server, or a thin internal MCP wrapper that logs requests. Step five: add spending limits, product access, and IP restrictions where available. Step six: remove the Session2API MCP entry from any shared config and rotate the personal session by signing out.

That migration path is the article's practical answer. Session2API can answer whether search helps. The official API path answers whether the team can operate it.

Rate Limits Do Not Make It Safe

The token pool is a good implementation detail, not a policy guarantee. token_pool.py rotates across tokens, applies a 5 requests per second token bucket per token, and disables tokens that expire. client.py maps 401, 403, and login redirects to expired-token errors, and treats 429 as rate limiting.

That keeps the local tool from hammering one token by accident. It does not answer the larger questions: whether using session access this way is allowed, whether the account owner wants an agent to issue searches through their personal account, or whether summarizer calls should touch sensitive URLs. A rate limiter is guardrail plumbing. It is not governance.

If a team needs high-volume search, multiple tokens are the wrong signal. Move to the official API and set budget controls.

The Summarizer Is the Most Fragile Part

kagi_summarizer calls /mother/summary_labs, and the code comments call that endpoint experimental. Kagi's official Universal Summarizer API is documented separately: it uses API keys, API credits, explicit engines, summary types, target languages, and a public /summarize endpoint.

That difference should shape the article verdict. Search through session HTML is already brittle; summarizer through an internal endpoint is more brittle. If a reader needs summaries for one local research session, this may be acceptable. If a product or agent routine depends on summaries, use the official Summarizer API and handle cost, cache policy, target language, and failure modes directly.

Do not build an agent memory or publishing pipeline on an undocumented summarizer endpoint and then act surprised when a page change breaks it.

When It Belongs in a Claude Code Workflow

The good use case is narrow: a single developer already pays for Kagi, wants Kagi search inside a local Claude Code session, and is comfortable treating the session token as a local secret. The MCP should be user-scoped, not project-scoped. It should run on stdio, not exposed over HTTP. It should be tested with public web queries before the agent is allowed near private URLs.

A responsible trial looks like this:

uvx kagi-session2api-mcp --help
claude mcp list

Then ask Claude Code to search for public documentation, not a private customer record. Review whether the agent follows result URLs, asks for confirmation before using sensitive data, and separates Kagi snippets from verified source content. If the trial is valuable, write down the workflow. If the workflow needs to be shared with other developers, stop and migrate to the official API path.

Failure Modes to Watch

There are five failure modes worth naming. First, token leakage: the Session Link logs into an account, so a leaked token is not just a narrow API secret. Second, parser drift: the HTML selectors can stop matching when Kagi changes the page. Third, internal endpoint drift: /mother/summary_labs is not the same kind of contract as Kagi's documented /summarize API. Fourth, prompt injection: search results and summarized pages are untrusted content entering the agent loop. Fifth, account policy risk: the README itself warns that the approach may violate Kagi terms.

That does not make the project worthless. It makes the boundaries non-negotiable. Keep it local. Keep tokens out of git. Avoid HTTP transport unless you have a concrete network boundary. Do not run it for unattended background agents. Do not use it for team search without consent from the account owner and a support plan.

Adoption Verdict

Kagi Session2API MCP is worth publishing because it teaches a concrete agent-integration lesson: MCP makes a personal account capability feel like a normal tool, but the credential behind that tool still decides the risk. The implementation is clear enough to inspect: FastMCP tools, session-cookie clients, token rotation, HTML parsing, formatted results, and config file handling.

Use it when the goal is a local proof of value for Kagi search inside Claude Code. Skip it when the goal is durable team search, production summarization, compliance-friendly logging, or anything that should survive endpoint changes. The official API and official Kagi MCP exist for that side of the line.

Kagi Session2API MCP is publishable as a session-token boundary article: useful for local Claude Code experiments, but not a substitute for Kagi's official API or official MCP in team workflows.

Practical takeaway

If you test it, keep the token in ~/.config/kagi-session2api-mcp/config.toml, run chmod 600, point Claude Code at KAGI_SESSION_CONFIG, verify with claude mcp list, run one public query, confirm no token appears in repo files, and migrate to Kagi's official API or official MCP before sharing the workflow with a team.