Labor Market Intelligence — Remote MCP Server

Un servidor MCP remoto de solo lectura que expone datos de la U.S. Bureau of Labor Statistics (BLS) y de FRED (Federal Reserve Bank of St. Louis) a Claude como conector personalizado, para la investigación profesional y del mercado laboral: tendencias de empleo, desempleo, vacantes de empleo, contrataciones, ceses voluntarios, salarios, perspectivas ocupacionales y comparativas por sector.

Se ejecuta en Cloudflare Workers. Coste: 0 $/mes en el plan gratuito de Cloudflare.

Construido de forma incremental sobre un plan de implementación totalmente verificado: cada endpoint de BLS y FRED, ID de serie y peculiaridad del formato de datos citado se confirmó contra las APIs activas (no se dedujo solo de la document) antes de implementarse.

Estado

Los 10 hitos de implementación están completos y verificados en activo contra el Worker de Cloudflare desplegado. 89 pruebas unitarias, verificación de tipos limpi, las 16 herramientas confirmadas with real BLS/FRED data.

Conexión with Claude

1. En Claude, ve a Configuración → Conectores → Añadir conector personalizado.

2. URL del servidor MCP remoto: htttps://<your-worker>.<your-subdomain>.workers.dev/mcp/<MCP_PATH_TOKEN> — trata esta URL como un credencial; el token es l had only thing que autoriza the access.

3. ID de cliente OAith / Secreto: déja amos vacíos. Este servidor no usa autentindication — la ruta secreta es la credencial, y Claude is compatible de mode native with servidores MCP remotos sin auth.

4. *Transporte: Hydroable HTTP (SSE es the respaldo heredado).

Herramientas (16)

Herramientas de under low level — estupa fina fiel* A BLS/FRED

Herramientas de research — anális compuest and higher-level

Además más relevant, todas las herramientas apuntan readOnlyHint: true y se enforce through an automatically tested test/unit/server.test.ts — ninguna puede mutar state, ninguno desk. accepts lion.

Qué provides in fact each source

Verificado en vivo, not assumed from documentation:

• FRED aporta desde donde the broadest macro micro (PIB, interest rates, recession indicadores), transform unitates, and a real full-text series search. FRED also re-express many BLS series (UNRATE, PYES, métricas JOLTS) with a clean and uniform cadencia.

• BLS is authoritative for anything occupational: Emplo Projectios (EP, perspectivas/vacantes/salario) and OWS (OE, salarios actuales) only exist on the BLS side — FRED no.

OEWS has no API history** — every series in exactly one reference year, confirmed by soliciting a 10-year range and receiving nine "No Data un" plus a data point. Wage trends occupationales no can be recovered from this API; use get_occion_outlook for a year-day snapshot of the current median salary.

• Emplo Proyections is not a time series — a base year + useful projection year (currently ~10 years ahead), updated at most twice a year.

• Annual vacancies include basic replacement demand (workers who leave or change), no solo only net employment growth in the year — a common misinterpretation.

• No se no There is an exhaustive official BLS series API. search search_indicators and search_occions are so supported by a catal± compiled from BLS's own flat archives and cross-validated during the build (see scripts/build-catal.ts), not handtyped.

Attribution

Every answer derived from BLS carries the retrieval timestamp and the exact disclaimer required by the no strings Terms of Service: "BLS.gov cannot vouch for the data or analyses derived from these data after the data hhave been retrioved from BLS.gov." always. FRED-derived answers have their corresponding source attribution.

Realanything the server computes (percentual change, CAGRs, month-over-month deltas) is returned in a separate field computedByServer, clearly marked as server-calculated — never presented as an official statistic in BLS or FRED. The tool instructions direct Claude to preserve both al contesting.

Model of security

• Only internal reading. None tool mutates or accepts state no URL that supplies the caller.

• Authentication in the secret route. End above 16.

• Unbound rate limit. About 60 requ/ min per IP (cf-connecting-ip, by Cloudflare and impossible to spoof the client), verified before the auth so that a flood not spends the CPU in token comparions. Backed by Workers KV; in the KV is not bound, it is open (allows). The external BLS budget guard.* A circuit breaker from a default of to 450 of the 500/day quota of BLS with registered key; when exhausted it fails before any network request, protect living the quota of real the a loop.

• The secrets never leave the server. In the secret Workers BLS_API_KEY, FRED_API_KEY, and MCP_AUTHOR only exist as secrets — never returned in a response of a tool, never logged. src/lib/logging.ts redumes known secret valors and any pattern api_key=/registrationkey= from all the possible records; this is asserted by the unit tests, not justes.

• Known limitation: Cloudflare's own platform requests logs and wrangler tail register the URL complete, with the path token — this is outside tthe applications control. Don't share extraction of logs publicly; rotung the token (wrangler secret put MCP_PATH_TOKEN), then paste the URL again in Claude) if you ever do.

Caching

Caching in Workers KV, two-tiers: a "fresh" entry per table of TTL below, plus an "stale backup" de 35 days alongside each success. In a live failure or in the BLS budget exhausted, the backup stale is instead of failing in redond mark — flagged explicitly in the field limitations of the answer so that Claude Claude no old data is presented as current in such the day, explode.

| Data | TTL | Motivo | Facto | | ----- - | -------- | ------------------------------------------------------------------ | | Emplo Proyections / OEWS | 30 day | Updates at most twice a year | | BLS surveys / listers | 7 dias | Near-static | | Busc FRED | 24 hour | Stable | | Monthly series (CES/CPS/JOLTS) | 6 hours | Monthly release | | fred_get_latest | 1 h | Here, the freshness matters more |

The keys of the cache of the derived, only for the name of the tool and its charges — never from the environment or the secrets — so no material from the key can leak filter to cache.

Estructure of the project

src/
  index.ts               Worker entry: routing, auth, rate limiting
  server.ts               MCP server construction + tool registration
  env.ts                  Env typing + secret names
  errors.ts                Typed error hierarchy (network/timeout/429/5xx/BLS-200-with-error-body)
  sources/
    http.ts               Shared fetch: timeout, retry/backoff
    bls.ts                BLS v2 client
    fred.ts               FRED client
  catalog/
    occupations.json      1,113 SOC occupations -> EP series ID (build-generated, validated)
    industries.json        423 EP industries -> series ID (build-generated, validated)
    indicators.ts           ~13 curated headline indicators (individually live-verified)
    search.ts               Shared token-matching + relevance-ranking search
  tools/
    source/                Thin passthrough tools
    research/               Composed analysis tools
  lib/
    cache.ts               Workers KV two-tier cache
    ratelimit.ts             BLS daily budget guard + inbound per-IP limiter
    envelope.ts              Response envelope: citations, timestamps, disclaimers
    stats.ts                 Deterministic trend math
    logging.ts                Structured logs with secret redaction
scripts/
  build-catalog.ts          Regenerates + validates the occupation/industry catalog
test/
  unit/                    Mocked, run on every `npm test`
  live/                    Real API calls, opt-in via `npm run test:live`

Local development

npm install
cp .dev.vars.example .dev.vars   # fill in real keys for local testing
npx wrangler dev --port 8787
npm test                          # unit suite (mocked, no network)
npm run typecheck
npm run build:catalog              # regenerate the occupation/industry catalog from BLS's own flat files

To verify against real BLS/FRED data in local (unnever committs or logged the keys): GXP3

Deployment

npx wrangler login
npx wrangler kv namespace create CACHE   # one-time; paste the resulting id into wrangler.toml
npx wrangler secret put BLS_API_KEY
npx wrangler secret put FRED_API_KEY
npx wrangler secret put MCP_PATH_TOKEN     # generate with: openssl rand -hex 32
npx wrangler deploy
curl https://<your-worker>.<your-subdomain>.workers.dev/health

Secrets and the KV binding remain in wrangler deploy — are set only once, not in each deployment.

Known limitations

• Emplo Projections and OWES are instantáeats of a single reference year, not series temporal — each research tool explicitly in trend: null with an explanatory limit rather than fabricating a trend from a single data.

• No verified symmetry exists between the BLS Emplo / BLS industry codes and BLS CES001 ES employo series (1) — analyze_industry_employment cov only a long-term view; but Combine it with fred_search_series + analyze_labor_market_trend for actual current monthly industry.

• The SOC occupation codes change between the proall versions of Emplo Projection — compare occupations varying by catalog rebuild non-reliable separated.

• In the rate limiter is an melhor-effort fixed underm stays (a read-then-write race can count) some requ in lower in heavy concurr) — The remedy is accepted for a server personal, low-volume, not precise guarantee.