docs: overhaul mcp docs #1927

TC-MO · 2025-09-15T20:38:35Z

Stremline the prose for clarity & conciseness
Remove outdated SSE section
Restructure the content
Adjusted description in frontmatter

Note

Restructures MCP docs with tabbed OAuth/Bearer client configs (Cursor, VS Code, Claude), adds tool selection and advanced/troubleshooting sections, updates links/frontmatter, and removes legacy SSE guidance.

Docs restructuring and content:
- Authentication & setup: Introduce tabbed configs for OAuth and Bearer token; add client-specific setup for Cursor, VS Code, and Claude Desktop using Tabs.
- Quick start split: Clarify hosted Streamable HTTP vs local stdio with updated examples and config snippets.
- Tool selection: Explain tools query/CLI flags with minimal and default examples; add UI configurator link.
- Available tools: Refresh table; add get-actor-output tool and note on retrieving full outputs.
- Advanced/troubleshooting: Add production best practices, rate limits/performance, and troubleshooting (auth, local env, actor issues).
Removals/cleanups:
- Remove legacy SSE transport section and related examples.
Metadata and links:
- Update frontmatter description and add toc_max_heading_level: 4.
- Update images/prose and GitHub links to apify/apify-mcp-server.

^{Written by Cursor Bugbot for commit 71640ce. This will update automatically on new commits. Configure here.}

Stremline the prose for clarity & conciseness Remove outdated SSE section Restructure the content Adjusted description in frontmatter

apify-service-account · 2025-09-15T20:43:48Z

Preview for this PR was built for commit f72c67f0 and is ready at https://pr-1927.preview.docs.apify.com!

apify-service-account · 2025-09-15T21:00:47Z

Preview for this PR was built for commit 68d98c36 and is ready at https://pr-1927.preview.docs.apify.com!

apify-service-account · 2025-09-15T21:11:38Z

Preview for this PR was built for commit f8d417e4 and is ready at https://pr-1927.preview.docs.apify.com!

apify-service-account · 2025-09-15T21:26:26Z

Preview for this PR was built for commit 796dca20 and is ready at https://pr-1927.preview.docs.apify.com!

apify-service-account · 2025-09-15T21:30:52Z

Preview for this PR was built for commit ff851083 and is ready at https://pr-1927.preview.docs.apify.com!

apify-service-account · 2025-09-16T16:03:05Z

Preview for this PR was built for commit cd071cad and is ready at https://pr-1927.preview.docs.apify.com!

TC-MO · 2025-09-16T16:33:11Z

@jirispilka @MQ37 as discussed back in the office and in the issue #1777. This PR aims to improve MCP docs.

I've streamlined them and cleaned up legacy section, cleaned up the language, restructured them for better logical flow & clarity, and based on this discussion on slack I've added a new section describing how to add the MCP server to popular editors like VSC & Cursor & Claude Desktop. I think this is vast improvement over what we had, but all feedback is welcome. I'll also try to research how to create deeplinks like Stripe has in their docs for easy install in Cursor & VSC

MQ37

Nice overhaul, thank you! Just a few comments regarding the content 👍

MQ37 · 2025-09-17T11:42:05Z

sources/platform/integrations/ai/mcp.md

-_Claude Desktop_: Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation.
+:::
+
+#### Text editor configuration


I know code is essentially text but I would call this Code editor configuration

Also Claude Desktop is not a text or code editor, so I would maybe just use "Client configuration"

BTW I like the DXT one click install block for the Claude desktop, that is really nice 👍

Yup, I admit Text editor config was a bit of placeholder but I do like Client configuration a lot thanks!

MQ37 · 2025-09-17T11:53:49Z

sources/platform/integrations/ai/mcp.md

-By default, the server is pre-configured with one Actor, `apify/rag-web-browser`, and several helper tools.
-The MCP server loads an Actor's input schema and creates a corresponding MCP tool.
-This allows the AI agent to know exactly what arguments to pass to the Actor and what to expect in return.
+For development environments, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing.


I would not mention this in context of development envs but rather that this is alternative approach for client that do not support remote MCP servers using the url mcp.apify.com

Makes sense, I'll rephrase

Agree with @MQ37

Also, this: "This approach gives you more control over the server configuration and is ideal for testing"
It does not give you more control over the server configuration. It just a different way of how to run it. Stdio might eventually die anyway

MQ37 · 2025-09-17T11:55:22Z

sources/platform/integrations/ai/mcp.md

-:::caution Important recommendation
+- Always use the latest version of the server by appending `@latest` to your npm commands.
+- Monitor your API usage through Apify Console to stay within your plan limits.
+- For optimal performance, batch related operations when possible and use Actor webhooks for long-running tasks instead of polling for results.


Can users somehow manage and use webhooks via MCP? I am not sure how would I do this myself since we do not support tasks. I would probably not mention this.

Yeah I might have went overboard here, I'll remove it

sources/platform/integrations/ai/mcp.md

Co-authored-by: Jakub Kopecký <themq37@gmail.com>

apify-service-account · 2025-09-18T09:10:22Z

Preview for this PR was built for commit b7d83fef and is ready at https://pr-1927.preview.docs.apify.com!

jirispilka

@TC-MO great work! This is really a big improvement, love it ❤️

I left a couple of suggestions.

jirispilka · 2025-09-18T20:10:30Z

sources/platform/integrations/ai/mcp.md

+## Quick start

-Before you start, make sure you have the following:
+You can connect to the Apify MCP server in two ways: use our hosted service for a quick and easy setup, or run the server locally for development and testing.


Here you write: "use our hosted service for a quick and easy setup, or run the server locally"

But then, just one line below, you have tittle "Streamable HTTP with OAuth".

Some users might not connected hosted service with Streamable HTTP with OAuth. I know it might be obvious, but still it would be able to reference it to remove some confusion.

jirispilka · 2025-09-18T20:13:22Z

sources/platform/integrations/ai/mcp.md

-By default, the server is pre-configured with one Actor, `apify/rag-web-browser`, and several helper tools.
-The MCP server loads an Actor's input schema and creates a corresponding MCP tool.
-This allows the AI agent to know exactly what arguments to pass to the Actor and what to expect in return.
+For development environments, you can run the MCP server locally. This approach gives you more control over the server configuration and is ideal for testing.


Agree with @MQ37

Also, this: "This approach gives you more control over the server configuration and is ideal for testing"
It does not give you more control over the server configuration. It just a different way of how to run it. Stdio might eventually die anyway

sources/platform/integrations/ai/mcp.md

jirispilka · 2025-09-29T07:43:33Z

@TC-MO I really like the changes you did, would you have time to finish it this week 🙏🏻 . Before MPC summit in London?

TC-MO · 2025-09-29T07:45:11Z

Hey! Yes I planeed to have it done before my vacation but in the end this didn't work out. I'm just now sitting down to finish this and have it released by tomorrow. Will that work for you?

jirispilka · 2025-09-29T10:54:13Z

Yeah, that would be great!

apify-service-account · 2025-09-30T21:50:22Z

Preview for this PR was built for commit 5800b41c and is ready at https://pr-1927.preview.docs.apify.com!

Co-authored-by: Jiří Spilka <jiri.spilka@apify.com>

apify-service-account · 2025-09-30T21:56:35Z

Preview for this PR was built for commit 5932f6cb and is ready at https://pr-1927.preview.docs.apify.com!

MQ37

Thank you for the rework - great job 👍 Please merge the #1932 and then LGTM

TC-MO · 2025-09-30T22:17:29Z

Oh! So sorry! I completely forgot about that PR, will take a look ASAP

MQ37 · 2025-10-01T07:59:05Z

sources/platform/integrations/ai/mcp.md

+
+:::tip One-click installation
+
+Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation.


Suggested change

Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation.

Download and run the [Apify MCP Server MCPB file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) for one-click installation.

I forgot to update the link and DXT was rebranded to MCP bundles (MCPB)

Thanks, I also forgot about this

Add `get-actor-output` tools info and merge into the #1927  --- > [!NOTE] > Documents a new `get-actor-output` tool for retrieving full Actor outputs, with a note on automatic inclusion, datasetId usage, and pagination/field filtering. > > - **Docs (MCP server)**: > - **New tool**: Add `get-actor-output` entry to the Available tools table. > - **Usage note**: Explain that it’s auto-included with Actor tools (e.g., `call-actor`, `add-actor`), used to fetch full output via `datasetId`, and supports limit/offset/field filtering. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit a46162b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup>  --------- Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-10-01T08:14:22Z

Preview for this PR was built for commit 71640cec and is ready at https://pr-1927.preview.docs.apify.com!

jirispilka

I did a quick pass, looks good to me. Thanks!

TC-MO · 2025-10-01T12:02:53Z

let's merge away then!

docs: overhaul mcp docs

3246f9b

Stremline the prose for clarity & conciseness Remove outdated SSE section Restructure the content Adjusted description in frontmatter

TC-MO self-assigned this Sep 15, 2025

TC-MO added documentation Improvements or additions to documentation. t-docs Issues owned by technical writing team. labels Sep 15, 2025

TC-MO requested review from MQ37 and jirispilka September 15, 2025 20:39

Merge branch 'master' into mcp-restructure

f72c67f

add troubleshooting section

68d98c3

slight adjustments to H2 paragraphs

f8d417e

change headings in troubleshooting section and add mdlint rule disable

796dca2

fix typo

ff85108

TC-MO mentioned this pull request Sep 16, 2025

Hey team, I tried to install http://mcp.apify.c... #1928

Open

add new section about MCP configuration for popular tools

cd071ca

TC-MO marked this pull request as ready for review September 16, 2025 16:15

MQ37 reviewed Sep 17, 2025

View reviewed changes

MQ37 mentioned this pull request Sep 17, 2025

docs: add get-actor-output tool #1932

Merged

Apply suggestions from code review

b7d83fe

Co-authored-by: Jakub Kopecký <themq37@gmail.com>

jirispilka reviewed Sep 18, 2025

View reviewed changes

address doc review

5800b41

Apply suggestions from code review

5932f6c

Co-authored-by: Jiří Spilka <jiri.spilka@apify.com>

TC-MO requested review from MQ37 and jirispilka September 30, 2025 21:52

MQ37 approved these changes Sep 30, 2025

View reviewed changes

MQ37 reviewed Oct 1, 2025

View reviewed changes

jirispilka approved these changes Oct 1, 2025

View reviewed changes

TC-MO merged commit 4b8bb6e into master Oct 1, 2025
11 checks passed

TC-MO deleted the mcp-restructure branch October 1, 2025 12:03


		:::tip One-click installation

		Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation.

	Download and run the [Apify MCP Server DXT file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.dxt) for one-click installation.
	Download and run the [Apify MCP Server MCPB file](https://github.com/apify/actors-mcp-server/releases/latest/download/apify-mcp-server.mcpb) for one-click installation.

docs: overhaul mcp docs #1927

docs: overhaul mcp docs #1927

Uh oh!

Conversation

TC-MO commented Sep 15, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apify-service-account commented Sep 15, 2025

Uh oh!

apify-service-account commented Sep 15, 2025

Uh oh!

apify-service-account commented Sep 15, 2025

Uh oh!

apify-service-account commented Sep 15, 2025

Uh oh!

apify-service-account commented Sep 15, 2025

Uh oh!

apify-service-account commented Sep 16, 2025

Uh oh!

TC-MO commented Sep 16, 2025

Uh oh!

MQ37 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

apify-service-account commented Sep 18, 2025

Uh oh!

jirispilka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jirispilka commented Sep 29, 2025

Uh oh!

TC-MO commented Sep 29, 2025

Uh oh!

jirispilka commented Sep 29, 2025

Uh oh!

apify-service-account commented Sep 30, 2025

Uh oh!

apify-service-account commented Sep 30, 2025

Uh oh!

MQ37 left a comment

Choose a reason for hiding this comment

Uh oh!

TC-MO commented Sep 30, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Oct 1, 2025

Uh oh!

jirispilka left a comment

TC-MO commented Sep 15, 2025 •

edited by cursor bot

Loading