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.

Exports complete synchronously and return short-lived artifact links. Semlens does not advertise durable MCP Tasks, task handles, task status, or task cancellation.

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.

These prompts are intentionally read-first. They should prove that the agent can inspect Semlens without changing your designs, exports, or publishing state.

Expected result: the agent can explain the connection, find recent designs, and inspect a chosen design 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, generation, templates, and design editing remain independent creative-system 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.

The Designs workflow turns the completed package into one bounded, editable draft. It chooses one primary message, compares purpose, dimensions, aspect ratio, field capacity, text limits, media slots, attribution, and Caveats, and maps only grounded content to inspected source fields. Research contains no saved image candidates. Media placement is a separate creative-system operation using independently inspected uploaded or approved media. The agent validates the fill plan and declines to create a draft when no inspected template can carry the message safely.

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, saved research, template inspection, autofill validation, and draft creation.

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. “Turn this into a design” uses the Designs workspace and create-design workflow instead.

“Find images” is not a Research write. The agent must use the appropriate image or design 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. When authorization inspection reports Create initial draft available, it also authorizes one initial editable draft. “Research only” saves when available and stops. Replacing materially different saved research requires explicit approval. An unchanged package reuses its current draft.

A changed retry after failed draft creation requires fresh approval. Exporting and publishing are always separate actions. Your MCP client may still show its own confirmation prompt.