Medialyst MCP

Medialyst is the data layer for your agent. The remote MCP server exposes a small set of authenticated research and monitoring tools:

https://medialyst.ai/api/mcp

Most tools share a service contract with Medialyst's public developer API. list_journalist_requests is intentionally MCP-only.

Authentication

You have two ways to connect, and both grant the same scoped, org-level access:

• OAuth — for chat clients like Claude.ai and ChatGPT. Paste the MCP URL, authorize Medialyst when prompted, pick your organization, and you're in. No API key to paste.
• API key — for clients that send an Authorization header (Claude Code, Cursor, Codex) and for CI. Create a key from Developers, store it in secret storage or an environment variable, and send it as a bearer token:

Authorization: Bearer <YOUR_API_KEY>

Required Scopes

Connect Your Agent

Claude.ai and ChatGPT (OAuth)

Add Medialyst as a custom connector with just the URL — no header, no key:

1. Settings → Connectors → Add custom connector
2. Name: Medialyst
3. Remote MCP server URL: https://medialyst.ai/api/mcp
4. Leave advanced settings empty. Add it, then authorize Medialyst with OAuth when prompted and choose your organization.

ChatGPT custom connectors are currently rolling out for Plus and Pro.

Claude Code

export MEDIALYST_API_KEY="<YOUR_API_KEY>"

claude mcp add --transport http --scope user medialyst https://medialyst.ai/api/mcp \
  --header "Authorization: Bearer $MEDIALYST_API_KEY"

Verify in Claude Code:

/mcp

Claude Desktop

{
  "mcpServers": {
    "medialyst": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://medialyst.ai/api/mcp",
        "--header",
        "Authorization: ${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <YOUR_API_KEY>"
      }
    }
  }
}

Cursor

{
  "mcpServers": {
    "medialyst": {
      "url": "https://medialyst.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MEDIALYST_API_KEY}"
      }
    }
  }
}

Then start Cursor from a shell where the key is exported:

export MEDIALYST_API_KEY="<YOUR_API_KEY>"
cursor .

Codex

[mcp_servers.medialyst]
url = "https://medialyst.ai/api/mcp"
bearer_token_env_var = "MEDIALYST_API_KEY"

Then export the key before starting Codex:

export MEDIALYST_API_KEY="<YOUR_API_KEY>"
codex mcp list

Command line (newsjack)

newsjack is the open-source PR CLI built on Medialyst. Connect it with one command:

newsjack login

Approve the browser prompt and the CLI authenticates with OAuth device login — no API key to copy out of the terminal. Install instructions live at newsjack.sh. CI and power users can still set a MEDIALYST_API_KEY instead.

Other Clients

Use the Streamable HTTP endpoint and bearer header directly:

MCP URL: https://medialyst.ai/api/mcp
Transport: Streamable HTTP
Header: Authorization: Bearer <YOUR_API_KEY>

If your client only supports stdio servers, bridge to the remote endpoint with mcp-remote.

Tool Surface

Only these 34 tools are exposed. Media-list creation, polling, and completed table reads use the same public API operations shown above; other table mutations and share-link creation stay outside the hosted MCP surface.

Example Workflows

Set up a project from one prompt

Ask your agent:

Create a Medialyst project for Acme, add our durable client facts and ranking preferences, upload the launch brief as Markdown, and tell me when the file is ready for media-list planning.

Expected sequence:

1. Call create_project and save the returned project id.
2. Call add_project_memory_line once per durable fact. Use one of About the client, Ranking preferences, Never, or Pitch voice; a ranking preference or hard exclusion needs a reason after a colon.
3. Call upload_project_file with a human-readable title and its text content. The title may omit an extension: Medialyst appends .md by default or .txt for mime_type: "text/plain". With no mime_type, .txt selects plain text and .md/.markdown selects Markdown. An explicit format and extension must agree.
4. Poll get_project_file until its status is ready or failed.

All project tools require projects:manage. Memory and file tools follow the app's plan rules and return PROJECT_CONTEXT_UPGRADE_REQUIRED on the Free plan. set_project_memory is a full-document compare-and-set operation: call get_project_memory first and pass its version as expected_version.

To set up Radar, use list_projects → get_project_memory → set_up_radar → list_radar_opportunities. Ground all five required RADAR.md sections in project memory; the API never auto-enrolls an organization when the Radar flag is off. Use run_radar for an additional scan. The setup-time scan does not count; two Scan-now runs are allowed per Radar local day.

Call get_radar before update_radar and pass its markdownVersion as expected_version. Use update_radar_settings to pause or resume scanning or change the local scan hour or digest setting. Slack delivery uses a per-Radar Incoming Webhook: pass slack_webhook_url plus slack_digest_enabled: true, and optionally send_test: true. During setup, a supplied webhook enables Slack unless slack_digest_enabled is explicitly false. Later URL replacements preserve the current enabled state. Set slack_webhook_url to null or an empty string to remove the destination and disable Slack. Webhooks are write-only secrets: get_radar and mutation responses return only redacted delivery.slack status and a masked tail, never the URL. These calls reuse the existing projects:manage scope. Send verdicts with send_radar_feedback, including undo, and use get_radar_today for the paginated, markdown-free organization view. list_radar_opportunities returns at most 50 items; when page.truncated is true, call it again with page.next_cursor.

Build and inspect a media list

Ask your agent:

Build a media list of up to 40 credits for US journalists covering enterprise AI infrastructure, wait for it to finish, and show me the completed rows.

Expected sequence:

1. Call create_media_list with prompt, target_list_size, and a stable request_options.idempotency_key. target_list_size is the maximum credit budget, not a promised number of journalists.
2. Save job_id, media_list_id, workflow_id, media_list_url, and results_url from the accepted response.
3. Poll get_media_list_job with job_id every 10 to 15 seconds until status is complete, failed, or cancelled. The response's next_tool field gives the next call and arguments.
4. On complete, call get_media_list with the returned media_list_id, include_rows: true, row_detail: "full", and limit: 100.
5. Continue with page.next_cursor until it is null.

{
  "prompt": "Find US journalists covering enterprise AI infrastructure.",
  "target_list_size": 40,
  "request_options": {
    "idempotency_key": "enterprise-ai-launch-2026-09"
  }
}

The three MCP tools are thin adapters over the canonical REST create, poll, and read operations. Authentication, organization isolation, scopes, plan and free-tier gates, effective credit budget, idempotency, errors, and response fields therefore follow the public API contract. A 404 from a poll or read may mean that the identifier belongs to another organization; do not guess or substitute identifiers.

Screen new journalist requests

Ask your agent to screen new source requests every hour:

List journalist requests observed after 2026-08-09T13:00:00Z. Keep draining pages, screen each request, and save the final next cursor for the next hourly run.

Expected sequence:

1. Call list_journalist_requests with since and an optional limit from 1 to 250.
2. Process the returned requests idempotently by stable id.
3. While page.has_more is true, call the tool again with only page.next_cursor as cursor.
4. When page.has_more is false, save that same cursor for the next hour.

See the Journalist Requests MCP guide for timestamp collision handling, the normalized schema, source exclusions, privacy policy, and a checkpointing cron example.

Track journalist moves

Ask your agent to poll journalist moves every morning (requires a Scale plan):

List journalist moves observed after 2026-08-14T00:00:00Z. Keep draining pages, record each move, and save the final next cursor for tomorrow's run.

Expected sequence:

1. Call list_journalist_moves with since and an optional limit from 1 to 250.
2. Process the returned moves idempotently by stable id.
3. While page.has_more is true, call the tool again with only page.next_cursor as cursor.
4. When page.has_more is false, save that same cursor for the next morning.

See the Journalist Moves API guide for the de-duplication rule, the match-state default, and a checkpointing cron example.

Look up articles and publications

Use lookup_article when you need canonical metadata for one known article; set include_markdown: true only when the extracted body is needed. Use lookup_articles for 1-10 URLs. Batch article lookup never includes Markdown.

Use lookup_publication to resolve an article or outlet URL to canonical publication metadata. Use lookup_publications for 1-25 cached/default URLs. When force_refresh: true, publication batches are capped at five URLs and may be rate-limited more aggressively, so prefer cached/default lookup unless stale metadata is unacceptable.

Article lookup costs 0.1 credit per successful URL. Publication lookup costs 0.01 credit per successful URL. Per-URL failures cost 0 credits for both, so batch budgets depend on successful results rather than submitted URL count.

{
  "urls": [
    "https://example.com/story-one",
    "https://example.org/story-two"
  ],
  "force_refresh": true
}

Research news and enrich journalists

Ask your agent:

Search recent AI agents coverage and find 5 journalists I should pitch on a related angle.

Expected sequence:

1. get_credit_balance
2. query_pr_calendar when the user needs planning moments or pitch timing
3. search_news with a specific recency window when discovering journalists from coverage
4. enrich_journalists with a known journalist reference or a selected article URL, plus fit_context.pitch
5. get_journalist_enrichment_job until the job is complete or failed

For a known journalist, use this canonical input:

{
  "from": [
    {
      "type": "journalist_reference",
      "name": "Jane Doe",
      "publication": "The Daily Example"
    }
  ]
}

Notes

• list_journalist_requests requires exactly one of an exclusive RFC 3339 since timestamp or the preceding opaque cursor. It is free, costs zero credits, requires no special scope, and returns at most 250 records per page.
• The journalist-request feed includes Connectively (formerly Featured), HARO, Twitter/X, LinkedIn, MentionMatch, and Substack for every authenticated account, all for free. The feed does not expose private email, paid contact data, upstream IDs, or credentials.
• Every list_journalist_requests response carries a mandatory top-level notice field. Screening, ranking, filtering, and summarizing are permitted; automating outreach is a Terms of Service violation. See Journalist Requests.
• list_journalist_moves requires exactly one of an exclusive RFC 3339 since timestamp or the preceding opaque cursor. It requires an active Scale plan, costs zero credits, returns at most 250 de-duplicated moves per page, and filters on when Medialyst observed each move — not the move's effective date.
• search_news returns up to 10 results per call. Use page: 2, page: 3, and so on for deeper coverage. Do not use the deprecated num parameter.
• query_pr_calendar is free, costs 0 credits per successful call, and returns source-backed PR moments with pitch timing fields.
• lookup_article accepts one absolute HTTP(S) URL and optional include_markdown; lookup_articles accepts 1-10 absolute URLs and has no Markdown option.
• lookup_publication accepts one absolute HTTP(S) URL and optional force_refresh; lookup_publications accepts 1-25 URLs normally or at most five with force_refresh: true.
• Article lookups cost 0.1 credit per successful URL; publication lookups cost 0.01 credit per successful URL; per-URL failures cost 0 credits.
• All four lookup tools require media_lists:manage and use the public REST routes, so auth, scopes, logs, credits, rate limits, and errors match direct API calls.
• MCP tools inherit the REST rate limits: 60 requests per minute per credential across the API, 10 article lookups per minute, 10 active enrichment jobs, and 30 polls per minute each for list_journalist_requests and list_journalist_moves. There is no daily cap. See Rate Limits, Journalist Requests errors, and Journalist Moves errors.
• journalist_reference requires name plus at least one of publication, domain, or url. Use it when the journalist is already known.
• article_url remains supported for enriching the author of a real article. Reference and article sources can be mixed in the same request.
• enrich_journalists is async-only and returns a job id immediately. fit_context.pitch returns scored journalist research and personalized angle output when available.
• options.wait and options.timeout_ms on enrich_journalists are deprecated compatibility no-ops. Poll get_journalist_enrichment_job instead.
• Public v1 has no send endpoint. Review and sending stay in the Medialyst app.

Troubleshooting

Build a Full Agent

Medialyst is the data layer. If you want the whole PR workflow — finding angles, building a fit-scored journalist list, and drafting pitches — use newsjack.sh, the open-source agent built on Medialyst by the team behind it. It connects with OAuth device login and ships opinionated skills for the full PR loop, so you don't have to assemble the primitives yourself.

Prefer to build your own agent on the raw primitives? See PR Agents on Medialyst.