Documentation

What is Aware?

Aware is an MCP server that gives Claude awareness of your world — weather, time, daylight, news, social trends, market data, public holidays, and the operating conditions of the AI services your environment depends on.

One MCP connection. Real-time data from a configurable set of sources. Your AI sees only what you choose to share.

Use cases

Aware is ambient context, not a search tool. You don’t name the source — Claude reads what’s in scope and answers from there.

• “What’s on the news today?”
  Headlines from your configured RSS feeds, NewsData topics, and any active presets — no need to tell Claude where to look.
• “What should I wear for my walk?”
  Current weather, air quality, and daylight remaining. Claude answers with the texture of the actual day, not a generic temperature read.
• “Is GitHub down?”
  Operating Conditions surfaces live status across Anthropic, OpenAI, Cloudflare, AWS, GitHub, Discord, and npm in one call.
• “How has the world shifted this week?”
  aware_what_changed summarises weather trends, daylight progression, and news momentum across the past 1–5 days.
• “Should we start dinner soon?”
  Time of day, sunset time, and daylight remaining give Claude the texture of evening rather than a clock reading.
• “Worth checking the markets today?”
  Stock quotes, market news, and FRED economic indicators in one scan.

Quick start

Option A — Claude.ai (web, desktop, mobile)

1. Open Settings → Connectors → Add custom connector.
2. Server URL: https://aware.codependentai.io/mcp
3. Sign in with Google or magic link when prompted.
4. The connector handles the rest. Tools appear automatically inside Claude.

Option B — Claude Code

Generate an API key at /settings, then add to your .mcp.json or ~/.claude.json:

{
  "mcpServers": {
    "aware": {
      "url": "https://aware.codependentai.io/mcp",
      "headers": {
        "Authorization": "Bearer ak_your_api_key_here"
      }
    }
  }
}

Authentication & permissions

Aware uses different auth depending on where you connect from:

• Claude.ai web, desktop, mobile — OAuth 2.1 with PKCE. You authorize the connector explicitly; Claude handles token storage and refresh.
• Claude Code & other MCP clients — Bearer API key (ak_... prefix), generated at /settings.

Scopes & permissions

Aware requests a single scope: mcp:read. With it, Claude can:

• Read public data from your configured sources (weather, news, social, market, holidays, infra).
• Read your Aware config so tools know which sources are enabled.
• Modify your Aware config via aware_configure and aware_reset — never any third-party account.

What Aware does not access

• Your messages, conversation history, or any other Claude data.
• Your accounts on Reddit, YouTube, or any third-party service — we use public endpoints only.
• Health data, financial accounts, or other sensitive PII.
• Precise location — only the city you configure.

Revocation

Disconnect from Claude.ai → Settings → Connectors, or delete API keys at /settings. Full account deletion (including config wipe) is one button on the settings page.

Tools

Environment

What’s around you right now.

• Weather aware_weather
  Current conditions plus optional 5-day forecast. Requires an OpenWeatherMap key.
• Time Context aware_time
  Local time, day of week, time-of-day, season, day progress.
• Daylight aware_daylight
  Sunrise, sunset, daylight hours, civil twilight. Trend vs. yesterday.
• Sky aware_sky
  Moon phase, illumination percentage, days until next full moon.
• Air Quality aware_air
  AQI plus PM2.5, ozone, NO₂. Uses your existing OpenWeatherMap key.
• Public Holidays aware_calendar
  Upcoming public holidays for your country, via Nager.Date.

Signals

What’s happening in the world.

• News aware_news
  Headlines from configurable RSS feeds and topic filters. Optional NewsData key. Registered.
• Social aware_social
  Trending posts from Reddit, Hacker News, and YouTube. Configurable subreddits. Registered.
• Market aware_market
  Stock quotes, market news, and economic indicators from Finnhub and FRED. Registered.

Operating Conditions

The state of the internet your AI runs on.

• Operating Conditions aware_infra
  Live status of Anthropic, OpenAI, Cloudflare, AWS, GitHub, Discord, and npm. No API key required.

Reflection

How the world has shifted recently.

• What Changed aware_what_changed
  One snapshot per day for the last 1–5 days — weather shifts, daylight changes, news movement. Registered.

Composite

Everything at once.

• World Check aware_world_check
  Full snapshot across every enabled source. Renders as a fullscreen dashboard inside Claude.ai.

Configuration

Manage Aware from inside Claude.

• Aware Status aware_status
  Show your current config and which sources are wired up.
• Configure Aware aware_configure
  Update timezone, location, news topics, RSS feeds, social subreddits, and preferences. Writes to your Aware config.
• Reset Aware aware_reset
  Wipe config and start fresh. Requires explicit confirmation. Destructive.

Annotations: Every tool except aware_configure and aware_reset is read-only (readOnlyHint: true). aware_reset is marked destructiveHint: true. Both writers only ever modify your Aware config — never third-party accounts.

Tier: All tools are free. Tools marked Registered require a free signed-in account (so we can store your topic and feed lists between sessions).

Sources & data providers

Where each tool gets its data. Aware is a thin layer — we call public APIs and providers directly, then merge, cache, and present.

• Weather & Air Quality OpenWeatherMap Free key required
• Time Context System (your configured timezone) No key
• Daylight Computed (NOAA solar algorithm) No key
• Sky Computed (lunar cycle) No key
• News NewsData.io and your RSS feeds NewsData key optional
• Social Reddit JSON, Hacker News API, YouTube Data API YouTube key optional
• Market Finnhub (quotes) and FRED (economic indicators) Free keys required
• Public Holidays Nager.Date No key
• Operating Conditions statuspage.io endpoints plus AWS RSS No key

Presets

One-click bundles you can apply to expand News and Social configuration without editing fields by hand. Apply or detach in Settings → Sources, or via the /api/presets endpoints. Presets stay linked — when we add new feeds, your config picks them up automatically.

• AI Ecosystem ai-ecosystem
  Model releases, AI safety research, and the people shaping the field. Curated feeds from Anthropic, Hugging Face, Simon Willison, and Jack Clark, plus the most active AI subreddits.
• UK News uk-news
  British politics, economy, and the day in the UK. BBC, Guardian, and Telegraph feeds plus UK-specific subreddits.
• Tech News tech-news
  Industry coverage from Ars Technica, BBC Tech, The Verge, and TechCrunch. Pairs well with AI Ecosystem if you want the broader tech beat alongside.
• Crypto Watch crypto-watch
  Bitcoin, Ethereum, and the broader crypto market. Cointelegraph and Decrypt feeds plus the major crypto subreddits.
• Science Daily science-daily
  Research and discoveries from Science, Nature, and ScienceAlert. Spans physics, biology, climate, and space.

Configuration

Two ways to configure Aware:

1. Web dashboard — /settings. Sticky section nav (Account, Location, Presets, Sources, Preferences, Data) with form-based editing. Best for the first-time setup and managing API keys.
2. aware_configure tool — From inside Claude. Add or remove RSS feeds, news topics, social subreddits, and toggle sources without leaving the conversation.

FAQ