# Reported issues for Atlas

Pod holds 24 of 385 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user.

Back to [Atlas](/mcp/atlas-2).

## Most discussed

### PRD: MCP V2 — Prime-Time MCP Server (hardening + protocol uplift + configuration surface)

> Synthesized from a full multi-agent review of the V1 MCP setup + six V2 research streams. **Grilled to resolution via `/grill-with-docs` on 2026-06-13** — all four open questions are now decided (see **Resolved decisions** below), the security model is captured in [ADR-0016](https://github.com/AtlasDevHQ/atlas/blob/main/docs/adr/0016-mcp-v2-security-model.md), and the `surface`→`origin` rename in [ADR-0015](https://github.com/AtlasDevHQ/atlas/blob/main/docs/adr/0015-agent-origin-not-surface.md

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/3483) · 2026-06-13 · closed · outside contributor · 3 comments

### feat: ES/OpenSearch datasource — publish package + staging cluster + matrix soak

## Parent
#3259

## What to build
**HITL / operator.** Bootstrap `@useatlas/elasticsearch` on npm, wire CI to publish subsequent versions, provision staging Elasticsearch + OpenSearch clusters + read-only credentials, and add the datasource to the staging datasource-matrix soak (#3253) so every connection type is exercised pre-release.

> **npm bootstrap (chicken-and-egg):** npm trusted publishing (OIDC) can't be configured for a package name that doesn't exist yet — so the FIRST publish must be

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/3272) · 2026-06-06 · closed · outside contributor · 11 comments

### feat: native Elasticsearch/OpenSearch datasource plugin

Atlas supports six datasource kinds today — Postgres + MySQL natively, and ClickHouse/Snowflake/DuckDB/Salesforce/BigQuery as published `@useatlas/*` datasource plugins. There is **no Elasticsearch/OpenSearch support**, despite ES/OpenSearch being one of the most common analytics/log stores teams want a text-to-query agent over. This issue scopes adding it as a native plugin.

**Good news: the abstraction already exists and fits cleanly.** Unlike REST datasources (which required building the who

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/3256) · 2026-06-06 · closed · outside contributor · 5 comments

### chore(mcp): Claude Desktop catalog — operator-side submission (off-repo half of #2077)

## Context

[#2077](https://github.com/AtlasDevHQ/atlas/issues/2077) was *Claude Desktop catalog submission, properly resourced* and bundled both in-repo and off-repo work. The in-repo half shipped in [#2195](https://github.com/AtlasDevHQ/atlas/pull/2195) (catalog-shaped tool annotations doc, MCP-named privacy section, branding pack with `mark.svg` + `mark-1024.png`, README cataloging assets, plus a `catalog-annotations.test.ts` guard that fails CI if the per-tool table drifts from `SEMANTIC_TOO

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/2200) · 2026-05-08 · open · outside contributor · 4 comments

### feat(api,mcp): Phase 1 — durable Postgres-backed MCP session store via Better Auth secondaryStorage

## Context

ADR `.claude/research/mcp-session-store.md` records the architecture decision: Atlas runs single-replica MCP per region today (forced by Railway's random load-balancer), with Postgres-backed durable session store as the Phase 1 scaling answer. This issue is the implementation work for Phase 1.

**Do not start this issue speculatively.** It exists in advance so the spec is ready when the trigger fires; opening it without trigger evidence is over-engineering.

## Trigger conditions

Be

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/2109) · 2026-05-06 · open · outside contributor · 3 comments

### feat(auth): agent-auth provider on top of OAuth 2.1 (post-#2024)

> **Sibling to #2024.** OAuth 2.1 + DCR (#2024) gives MCP clients a transport-layer identity model. This issue layers the [Agent Auth Protocol](https://agentauthprotocol.com) on top — capability-based authorization, delegated/autonomous modes, and approval flows — using `@better-auth/agent-auth`. Opt-in via `ATLAS_AGENT_AUTH_ENABLED=true` until the upstream spec stabilizes.

## Why a sibling and not an extension of #2024

#2024 ships frozen specs (RFC 7591/8414/9728, OAuth 2.1) that mature MCP c

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/2058) · 2026-05-04 · closed · outside contributor · 5 comments

### chore(mcp): list Atlas in MCP registries before 1.4.0 close (mcp.so + modelcontextprotocol/servers)

## Problem

`bunx @useatlas/mcp init` (#2018) solves install-once-you-know-about-it. It does NOT solve discovery. Agents and users find MCP servers via:

- [mcp.so](https://mcp.so) — third-party registry
- `modelcontextprotocol/servers` — official upstream repo, third-party section
- Increasingly: Claude Desktop's built-in catalog

If Atlas isn't listed at 1.4.0 launch, we ship an installer no one finds. Distribution surface is the whole point of an agent-first milestone.

## Proposal

Submit At

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/2027) · 2026-05-03 · closed · outside contributor · 4 comments

### feat(mcp): SaaS MCP auth + hosted endpoint at `mcp.useatlas.dev`

> **Updated 2026-05-04 — design pivot.** Issue body rewritten in place to track the OAuth 2.1 implementation. The original design (custom `mcp_tokens` bearer + RFC 8628 device-code flow) shipped as PR A (#2054) and PR B (#2056); PR C drops both and pivots to `@better-auth/oauth-provider`. Rationale below.

## Why we pivoted

The MCP authorization spec (2025-03-26 onward) requires the resource server to speak **OAuth 2.1 + PKCE + Dynamic Client Registration (RFC 7591)** and publish `/.well-known/

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/2024) · 2026-05-03 · closed · outside contributor · 4 comments

## Most recent

### fix(sdk): the widget can stage a REST write it can never confirm

Found while grilling #5485. Pre-existing, shipped, and out of that issue's scope — filed on its own rather than folded in.

## The bug

`executeRestOperation` stages an allowlisted write and returns `needs_confirmation` rather than firing it. The chat surface is then expected to render a confirm-before-write banner, which POSTs the replay payload to `POST /api/v1/rest-operations/confirm`.

**The embeddable widget can reach the tool and cannot render the banner.**

- `@useatlas/react` calls the s

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5495) · 2026-08-27 · closed · outside contributor · 0 comments

### sec(deps): better-auth 1.7 is a SCIM redesign and an OAuth resource-binding migration, not a minor bump

Split out of #4903, which is where the last two advisories live. Attempting the bump inside #5490 established that `^1.6.25 → ^1.7.1` is **not a version bump on this codebase** — it is two separate migrations wearing one version number. Recording the full measured scope so whoever takes it does not rediscover it.

## Why it cannot be split, or deferred to core-only

The obvious escape — hold `@better-auth/scim` at 1.6.25 and move everything else — does not exist. The peer pins are exact and conf

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5493) · 2026-08-27 · closed · outside contributor · 2 comments

### decide(adr-0038): Layer 2's rename has no carrier since retrieval depth left the cut — and its window closes silently at v1.0.0

[ADR-0038](https://github.com/AtlasDevHQ/atlas/blob/main/docs/adr/0038-the-atlas-is-the-product-the-brain-is-the-category.md) Layer 2 — the `searchBrain` tool name and the `tier` wire enum values — has no carrier and no issue. It is [Lane D](https://github.com/AtlasDevHQ/atlas/blob/main/docs/prd/company-atlas-completion-plan.md#lane-d--the-layer-2-rename) of the completion plan, the only **UNFILED** row left in it, and the only item in the whole plan with an expiry.

**This issue is the decision

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5469) · 2026-08-26 · closed · outside contributor · 1 comment

### fix(cli,auth): atlas login 404s on /api/auth/device/code across all prod hosts and staging

Found while trying to obtain a prod session for #5345's statement 4.

## The claim

`atlas login` cannot authenticate against **any** deployed environment. The OAuth 2.0 device-flow endpoint returns `404` on all four prod hosts and on staging, while the rest of the auth handler on the same origins is healthy.

## Measured 2026-08-23

| Host | `GET /api/auth/get-session` | `POST /api/auth/device/code` |
|---|---|---|
| `api.useatlas.dev` | **200** | **404** |
| `api-eu.useatlas.dev` | **200** | *

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5404) · 2026-08-24 · closed · outside contributor · 0 comments

### fix(brain): retract needs a fact id, and every surface that could produce one excludes published observations

Found while attempting #5345's statement 4 against prod on `v0.2.16` — the release that shipped `retract` for exactly this population.

## The claim

`POST /api/v1/admin/brain-facts/{id}/retract` needs a fact `id`. **No surface this deployment exposes can produce the id of a published warehouse-derived fact.** The arc that shipped the verb closed, in the same milestone, every path to the identifiers the verb consumes.

## Measured against prod, all four surfaces

| Surface | Result | Why |
|---|

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5403) · 2026-08-24 · closed · outside contributor · 0 comments

### track(api): TanStack AI hits RC — measure the Vercel AI SDK coupling before the plugin-SDK contract freezes

## Context

TanStack AI entered the RC phase on 2026-08-21 ([tanstack.com/ai](https://tanstack.com/ai), [releases](https://github.com/TanStack/ai/releases), [r/reactjs thread](https://www.reddit.com/r/reactjs/comments/1vvd7ts/tanstack_ai_enters_the_rc_phase/)). It is a headless agent framework: the agent loop as composable primitives, ~11 official provider adapters plus `openaiCompatible`, 7 UI framework bindings (React, Vue, Solid, Svelte, Preact, Angular, Octane), AG-UI as the wire protocol, a

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5387) · 2026-08-22 · open · outside contributor · 0 comments

### docs(adr): ADR-0027 §74 says the raw-SQL off-switch is unbuilt — #4095 shipped 2026-07-01, and the 2026-08-18 note reasons about a reversed deferral

## ADR-0027 §74 describes a deferral that was reversed seven weeks earlier

`docs/adr/0027-executesql-over-rest-security.md:74` reads, in the present tense:

> - **A workspace-admin off-switch for raw SQL** (gate-1 analog) — deferred to the Architecture Backlog as #4095, shaped to slot into the gate-1 seam. **Not built now:** Atlas is pre-customer and raw SQL is already contained by member-floor + whitelist + RLS + approval.

**#4095 was built.** Greenlit 2026-06-29 ("pre-customer deferral no lo

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5350) · 2026-08-20 · closed · outside contributor · 0 comments

### track(mcp): MCP spec 2026-07-28 goes stateless — what is ours, what is Better Auth's, and what is blocked on the TS SDK

Spec release: https://blog.modelcontextprotocol.io/posts/2026-07-28/

**Not actionable yet — this is a tracking issue.** `@modelcontextprotocol/sdk@1.30.0` (what we pin, `^1.30.0`, in root, `packages/mcp`, `packages/cli`) was published **2026-07-27, one day before the spec**, and no 2.x exists on npm as of 2026-08-15. The announcement says the TypeScript SDK is updated; that release is not on the registry under `latest`. **Re-check before starting** — most of the work below is unreachable until 

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5250) · 2026-08-15 · open · outside contributor · 0 comments

### fix(eval): close the six residual eval-lane defects — tool contract, keyed comparison, throttle scoring, token usage, --json stdout, backup/restore

**Six defects in the eval lane, consolidated into one issue so they ship as one run.** They are individually small, but they collide on two files — `canonical-eval-mcp-llm.ts` and `canonical-eval-run.ts` — so every parallel split still has two workers sharing a file. One branch, one panel, no seam to collide on.

All six were found by, or during review of, the batch that made the real-model eval work for the first time (#5122, #5130, #5131, #5126, #5128).

⚠️ **Work them in the order below.** Pa

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5147) · 2026-08-11 · closed · outside contributor · 0 comments

### bug(cli): `--json` still emits non-JSON on stdout for `atlas eval` and `atlas query`

#5126 fixed `canonical-eval --json` so stdout carries the JSON payload and nothing else. **Two sibling commands still violate the same contract**, found while auditing for #5126's "sibling modes audited" criterion and recorded there rather than fixed.

The property is one line: **stdout under `--json` parses as JSON, with no stripping.** It is currently false for both commands below.

## 1. `atlas eval --json` — three polluters

- the `--resume` line
- `Baseline saved to: <path>`
- `printRegress

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5146) · 2026-08-11 · closed · outside contributor · 1 comment

### bug(eval): the eval's tool-output contract is split across two files and cannot read a multi-part result

Two defects on one seam, filed separately as #5135/#5137 and merged here: both land on `extractToolJson` / `joinTextContent` and `interpretResult`, and #5135's proposed destination module is the file #5137 rewrites. Split into two PRs, one moves the code and the other rewrites it — a conflict in either order.

Both found during the #5131 review (merged in #5133).

---

## Defect A — a multi-part result is unparseable, so a correct answer fails as `protocol`

`withTrialFooter` appends a prose tex

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5137) · 2026-08-11 · closed · outside contributor · 1 comment

### bug(eval): a throttled dispatch in --tool-selection is scored as a tool-selection miss (no assertNotRateLimited)

#5122 established that **a throttle is a harness fault, not a model fault, and must not be graded** — a rate-limited dispatch used to be charged to `recovery`, so the score moved with dispatch timing rather than tool-selection quality. `runMcpLlmEval` got `assertNotRateLimited`, which aborts the run loudly instead of producing a number.

`runToolSelectionEval` never got the equivalent. It has no rate-limit check at all, so a `rate_limited` envelope is simply whatever the model did next — and bec

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5136) · 2026-08-11 · closed · outside contributor · 1 comment

### chore(eval): pin TEXT_CONTRACT_TOOLS against the real registered MCP surface in the REQUIRED suite

#5131 exempted text-output tools (`explore`) from the eval grader's JSON/protocol check, spelled as a name list. The list's failure mode is ROT — rename `explore` and the exemption silently stops matching, restoring the bug — and that is closed today by `assertTextContractToolsPresent`, which anchors the list against the live discovered surface inside both eval binders.

That anchor is **loud but late**. It fires at boot of the eval run, and the real-model lane is weekly and paid. A rename would

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5135) · 2026-08-11 · closed · outside contributor · 1 comment

### bug(eval): a successful `explore` call fails its question — the unparseable/protocol check is applied to a text-output tool

**5 of the 8 failures on the eval's first real CI run were one grader defect**, and it only manifests in CI — four local runs never showed it.

All five artifacts are identical:

```json
{ "category": "protocol", "tool": "explore",
  "summary": "MCP tool explore returned non-JSON content",
  "response": { "raw": "total 4\ndrwxr-xr-x 1 user user 0 Jan 1 00:00 .\n…entities/\n…metrics/\n" } }
```

That payload is a **successful `ls -la`**. `explore` is a shell tool — text output IS its contract — a

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5131) · 2026-08-11 · closed · outside contributor · 1 comment

### bug(eval): the --mcp-llm acceptance floor never reaches the exit code — an early return skips process.exit, so any score is green

**`canonical-eval --mcp-llm` always exits 0, at any score.** The acceptance floor is computed, printed, and thrown away. Every green this job has ever reported is meaningless.

Found on the job's first-ever real CI execution ([run 31453800369](https://github.com/AtlasDevHQ/atlas/actions/runs/31453800369), 2026-08-11), minutes after #5039's secret was wired.

## The evidence, in one run

```
FAIL: 12/20 below acceptance floor 18          <- the eval's own verdict
eval-mcp-llm: gate passed (outcom

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5130) · 2026-08-11 · closed · outside contributor · 1 comment

### bug(eval): eval-mcp-llm scores 1/20 against its 18/20 floor on its first ever real run

**The job ran for the first time in its life and scored 1/20.** Acceptance floor is 18/20.

This is the acceptance work [#2119](https://github.com/AtlasDevHQ/atlas/issues/2119) Part B never got. The job was built, commented, and permanently green without ever executing (#5039: no secret; and until #5040 a `skipped` step counted as a pass). [PR #5121](https://github.com/AtlasDevHQ/atlas/pull/5121) fixed the auth fixture that would have 403'd it, which is what made a real run possible.

## The run

[Read the thread](https://github.com/AtlasDevHQ/atlas/issues/5122) · 2026-08-11 · closed · outside contributor · 1 comment

The remaining reports are on [the project's issue tracker](https://github.com/AtlasDevHQ/atlas/issues).