Conduit

A self-hosted RSS reader exposed as an MCP service, deployed on AWS ECS Fargate. Authenticated via AWS Cognito OAuth and callable directly from Claude on iPhone, iPad, and desktop.

How it works

Conduit runs as a FastMCP HTTP server behind an ALB. Claude authenticates via OAuth (proxied through FastMCP to AWS Cognito), then calls MCP tools to manage RSS subscriptions and fetch feed content. Feed items are fetched live on each tool call — there is no background polling or caching layer.

Claude → OAuth (Cognito) → ALB → ECS Fargate (Conduit) → DynamoDB
                                                         → RSS feeds (live HTTP)

MCP Tools

Tool	Description
add_feed(url, label?)	Subscribe to an RSS/Atom feed. Validates the URL before storing.
remove_feed(url)	Unsubscribe from a feed.
list_feeds()	List all subscribed feeds with URL, label, and addedAt.
get_feed_items(url, limit=50)	Fetch live items from one feed. Returns title, link, published, summary.
get_all_items(limit=200)	Fetch headlines across all subscribed feeds (no summaries). Use for time-based filtering on the LLM side.
get_article_content(url)	Fetch and extract full plain-text content of an article. Returns title, author, published, content (≤100k chars).

Project Structure

conduit/
├── src/conduit/
│   ├── server.py      # FastMCP app, OAuth wiring, tool registration
│   ├── feeds.py       # HTTP fetch + parse (feedparser), article extraction (trafilatura)
│   └── storage.py     # DynamoDB CRUD for feed subscriptions
├── infra/
│   ├── vpc.yaml
│   ├── storage.yaml   # DynamoDB table
│   ├── cognito.yaml   # Cognito user pool + app client
│   ├── networking.yaml # ALB, ACM cert, Route 53
│   ├── ecs.yaml       # ECS Fargate cluster, task def, IAM roles
│   └── params/
│       ├── dev.json
│       └── prod.json
├── seeds/feeds.opml   # Replace with your OPML export for local dev
├── tests/
├── docker-compose.yml
├── Dockerfile
└── Makefile

Local Development

Prerequisites: Docker, Docker Compose, AWS CLI (for production deploys)

# Replace seeds/feeds.opml with your own OPML export first (optional)
make local

This starts:

• Conduit on http://localhost:8000 with AUTH_DISABLED=true
• DynamoDB Local on port 8001
• An init container that creates the conduit-feeds table

On startup, Conduit parses seeds/feeds.opml and pre-populates the feed list for the local user.

Connect Claude Desktop or any MCP client to http://localhost:8000/mcp.

Deployment

Dev

Five CloudFormation stacks, deployed in order:

make deploy-all ENV=dev

Or individually:

make deploy-vpc ENV=dev
make deploy-storage ENV=dev
make deploy-cognito ENV=dev
make deploy-cognito-secret ENV=dev   # stores client secret in SSM Parameter Store
make deploy-networking ENV=dev
make deploy-image                    # builds and pushes Docker image to ECR
make deploy-ecs ENV=dev

Prod

Same sequence, passing ENV=prod:

make deploy-all ENV=prod

Before deploying prod for the first time:

1. Set Domain in infra/params/prod.json to your production domain (e.g. conduit.example.com).
2. Ensure a Route 53 public hosted zone exists for the root domain in the same AWS account — make deploy-networking looks it up automatically.
3. After deploy-cognito, run make deploy-cognito-secret ENV=prod to store the Cognito client secret in SSM Parameter Store at /conduit/prod/cognito-client-secret. The ECS task reads it from there at runtime.
4. Create a Cognito user for each person who should have access: aws cognito-idp admin-create-user --user-pool-id <id> --username <email>.

Environment parameters live in infra/params/dev.json and infra/params/prod.json. The Domain parameter must match a Route 53 hosted zone in the same account.

To tear down:

make destroy-dev    # or destroy-prod, destroy-all

Authorization Model

Every MCP tool call is scoped to the authenticated user. Conduit extracts the sub claim from the Cognito JWT and uses it as a partition key (user#<sub>) in DynamoDB. This means:

• A user can only list, add, or remove their own feed subscriptions — there is no cross-user visibility.
• get_feed_items enforces subscription ownership: it rejects requests for feeds the calling user has not subscribed to.
• get_article_content does not check subscriptions — any authenticated user can fetch article content from any URL, since the URL comes from feed items they already have access to.
• In local dev (AUTH_DISABLED=true), all operations use the hardcoded identity local-dev-user. This mode must never be enabled in production.

Environment Variables

Variable	Required	Description
AUTH_DISABLED	No	Set to true to bypass Cognito. Never set in production.
DYNAMODB_TABLE	Yes	DynamoDB table name (conduit-feeds)
AWS_REGION	Yes	AWS region
COGNITO_USER_POOL_ID	Prod	Cognito User Pool ID
COGNITO_APP_CLIENT_ID	Prod	Cognito App Client ID
COGNITO_CLIENT_SECRET	Prod	Cognito App Client secret
DOMAIN	Prod	Service domain (e.g. conduit.example.com)

Development Commands

make lint       # ruff check src/
make format     # ruff format src/
make typecheck  # mypy src/
make test       # pytest

Tech Stack

• Python 3.12, FastMCP, feedparser, trafilatura, boto3
• AWS: ECS Fargate, ALB, ACM, Cognito, DynamoDB, Route 53, SSM, ECR
• Infra: CloudFormation, Docker (multi-stage, non-root)
• Quality: ruff, mypy (strict), pytest, gitleaks (pre-commit)