Semlens MCP

Add this as a Streamable HTTP or remote HTTP MCP server in your agent. The hosted server handles Semlens authentication through the agent's OAuth flow.

https://agents.semlens.com/api/mcp

Compatible clients automatically negotiate modern MCP 2026-07-28. Stateless legacy MCP 2025-11-25 remains available during the compatibility rollout.

Public discovery and tool-list metadata may be cached for five minutes, but the hosted endpoint still requires OAuth before it serves those requests. Clients with multi-round-trip support can answer a bounded clarification inside an ambiguous Board request; other clients receive the same clarification as a normal tool result and can retry.

curl -X POST https://agents.semlens.com/api/mcp \
  -H "Authorization: Bearer ${SEMLENS_MCP_ACCESS_TOKEN:?set a short-lived token}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{}}'

Prefer your client's managed OAuth flow. The manual diagnostic reads a pre-set short-lived environment variable so a token is not written into shell history; command arguments may still be visible to local processes. HTTP 401 is expected when the token is missing or invalid. Never extract a managed client token or paste a real token into support messages or documentation.

Normal setup includes native project editing. Requested source and sidecar saves use current permissions and exact versions directly. Preview-before-save is optional; capture/export and private results use explicit jobs. Full executable check remains unsupported; static lint covers selected HTML only. Social publishing is separate.

1. Add the server

   Use Semlens MCP as the server name and paste the hosted endpoint as the URL.

2. Authenticate

   When your agent asks, sign in and approve the connection. It uses your current account-wide access and workflow permissions from Account > Agent.

3. Test safely

   Run read-only checks first so the agent proves it can inspect context without editing anything.

Some agents can consume a markdown setup prompt directly. Use this companion page when you want the agent to read the endpoint, bundled skill path, first safe checks, and approval rules in one copy-friendly document.

https://semlens.com/docs/mcp/prompt.md

The prompt and this page describe the same hosted setup. Use either the Semlens plugin or manual MCP configuration; do not install both for the same server.

Use the Semlens CLI when you want terminal diagnostics, setup snippets, or update checks. You do not need the CLI to connect: the hosted MCP endpoint above is the canonical path.

mcp doctor is the single setup and endpoint preflight. Confirm authentication through your agent's MCP panel and a read-only Semlens inspection.

npm exec @semlens/cli@latest -- mcp doctor
npm exec @semlens/cli@latest -- mcp doctor --client codex
npm exec @semlens/cli@latest -- mcp repair codex
npm exec @semlens/cli@latest -- mcp setup codex
npm exec @semlens/cli@latest -- mcp setup codex --profile full
npm exec @semlens/cli@latest -- mcp setup claude

Tool-manifest changes require a restart, reconnect, or new agent task so the client rediscovers tools; they normally do not require OAuth again. Replacing a legacy endpoint may require authentication for the canonical endpoint. Neither action grants write access.

npm install -g @semlens/cli
semlens mcp doctor
semlens mcp doctor --client codex
semlens mcp repair codex
semlens mcp setup codex
semlens mcp setup codex --profile full
semlens mcp setup claude

These prompts are intentionally read-first. They should prove that the agent can inspect Semlens without changing your saved research or account assets.

Expected result: the agent can explain the connection, find Brand Kit and uploaded asset metadata before suggesting a next step.

Account > Agent > Design Rule is the canonical place to control Design creation instructions. Connected-agent Research uses the fixed Research contract while your personal agent applies its own research skills and methods.

Semlens returns the private story, current package, immutable contract, quality requirements, and freshness fields. The agent submits one complete package covering Facts, Angles, and Caveats. Facts owns citations and original-source attribution; partial section validation and saves are retired. Historical research remains readable from its saved data.

Angles produces meaningfully different, evidence-supported premises, grounded pulls, and high-level visual guidance. It does not treat headline rewrites as new angles, invent pulls, or choose an exact template.

Research packages are text-only. Image discovery, uploaded visuals and standalone image generation use separate operations.

Facts owns claim-level citations and original-source attribution. Citation notes identify what each source supports and disclose freshness, corrections, conflicts, interests, or weak evidence without treating popularity as verification.

Caveats records only unresolved material publication risks as concise publishing guardrails. It covers accuracy, freshness, conflicts, missing context, source limitations, rights, privacy or harm, misleading simplification, and audience-representation limits without treating boilerplate warnings as a substitute for sound research.

Native project creation from Research is not connected yet. Research contains no saved image candidates; uploaded assets and standalone image generation use separate operations.

Board list tools include deterministic signalNotes as compact triage labels, and story-detail tools include the full notes under storyMetrics. Reddit lane, rank, and observed activity context remain bounded secondary evidence; RSS may have no signal notes. Treat these indicators as prioritization context, not verification of the underlying claims.

Skills and plugins may teach an agent when to inspect the Design Rule, but they are optional adapters rather than its instruction source of truth. If the Design Rule changes during a creation workflow, the agent must inspect it again before creating a design.

Agents with paid Board access can inspect the same account-wide topics and sources as the Add Feed interface. Categories remain navigation-only. Following and unfollowing additionally require the account's Read & write authorization under Account > Agent. Catalog results include canonical topic-operation and direct-source targets.

Following a topic adds direct follows for its current active sources; it does not persist inherited topic membership. Unfollowing a topic removes direct follows for those current sources, while unfollowing one source removes that direct source only. Repeating the same operation is a successful no-change result.

Follows are account-wide rather than board-specific. A Home feed reads the same canonical follows whether they were created in Semlens or through MCP; external agent changes appear on the next normal Home refresh. The CLI remains a setup, discovery, and compatibility helper and does not add standalone follow commands.

Subreddits do not need a curated catalog entry. Use add_news_board_feed with a reddit_source_lane config, a lowercase subreddit name as sourceKey, its r/name label, a hot, new, or rising lane, and empty strings for topicPath and topicLabel.

Include a UUID requestId for each intentional Add and reuse it when retrying that request. A new ID permits another independent copy of the same feed. Adding a direct feed also follows that source; repeated follows do not consume another admission. There is no total board, feed, or follow cap, but new-source rate limits still apply. Inspect the feed with stories included, or refresh it, to read sourceStatus. Pending means the first update is still awaited, not that Reddit access has been confirmed. Provider restrictions can leave a saved source inaccessible. Source selections and boards remain private.

Private Board Lists group direct RSS and Reddit sources without changing Following or Home. Inspect Lists first, then copy canonical source targets from the source catalog when creating a List or changing its membership.

Use inspect_news_board_lists for bounded List and member summaries. Its addFeedConfig can be passed directly to add_news_board_feed; repeated List feed columns share the same current membership while keeping distinct feed instances. List writes require Read & write access and eligible paid Board access.

For Board research, your connected agent uses its own permitted web, search, or browser tools to verify public reporting and find public comments and videos. Semlens MCP handles private story inspection, research validation and owner-scoped saved research.

Research this Board story with Semlens MCP and save one complete Research package after verifying the public evidence:
[Paste the exact story title or public URL]

Semlens MCP does not provide general web search. If the agent's external research tools are unavailable, it should say that the story was not independently corroborated, use the contract's quality evidence for unavailable responsibilities, and never invent sources or results.

Give the agent the exact story title or public URL. The agent discovers one unambiguous story, inspects its current complete package and fixed contract, and asks for clarification when the match is ambiguous.

For factual preservation without creative work, the agent can inspect, validate, and save a separate lightweight factual Research artifact containing one headline, short excerpt, and original source. It does not require filler Angles, does not create a design, and is not a partial section save. Expanding it into complete Research still requires the full package and validator described below.

For a fresh story, the agent fills the inspected packageSkeleton, validates it with validate_news_board_story_research, saves with null expectedUpdatedAt and packageFingerprint plus the returned freshness token, then inspects again to verify readback. A stale response means re-inspect and rebuild from the newest package before retrying.

Connected Research uses the fixed Facts, Angles, and Caveats responsibilities. Facts owns citations and original-source attribution. Agents save all three as one complete package; partial section validation and section saves are retired. Native project creation from Research is not connected yet.

“Find images” is not a Research write. The agent must use the appropriate asset or image generation workflow without adding image candidates to the saved Research package.

“Research this story” authorizes research and self-review. It saves when authorization inspection reports Save research available. Replacing materially different saved research requires explicit approval.

Your MCP client may still show its own confirmation prompt.