docs: overhaul mcp docs #1927
docs: overhaul mcp docs #1927
Conversation
Stremline the prose for clarity & conciseness Remove outdated SSE section Restructure the content Adjusted description in frontmatter
TC-MO
added
documentation
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
Preview for this PR was built for commit |
|
@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 |
| _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 |
There was a problem hiding this comment.
I know code is essentially text but I would call this Code editor configuration
There was a problem hiding this comment.
Also Claude Desktop is not a text or code editor, so I would maybe just use "Client configuration"
There was a problem hiding this comment.
BTW I like the DXT one click install block for the Claude desktop, that is really nice 👍
There was a problem hiding this comment.
Yup, I admit Text editor config was a bit of placeholder but I do like Client configuration a lot thanks!
| 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. |
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Makes sense, I'll rephrase
There was a problem hiding this comment.
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
| :::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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Yeah I might have went overboard here, I'll remove it
Co-authored-by: Jakub Kopecký <[email protected]>
|
Preview for this PR was built for commit |
There was a problem hiding this comment.
@TC-MO great work! This is really a big improvement, love it ❤️
I left a couple of suggestions.
| ## 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. |
There was a problem hiding this comment.
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.
| 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. |
There was a problem hiding this comment.
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
| - **Apify documentation**: Search the Apify documentation and fetch specific documents to provide context to the AI. | ||
| - **Actor runs**: Get lists of your Actor runs, inspect their details, and retrieve logs. | ||
| - **Apify storage**: Access data from your datasets and key-value stores. | ||
| `https://mcp.apify.com?tools=actors,docs,apify/web-scraper` |
There was a problem hiding this comment.
| `https://mcp.apify.com?tools=actors,docs,apify/web-scraper` | |
| `https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser` |
There was a problem hiding this comment.
Let's not include apify/web-sraper . This is a universal scraper where you need to define custom pageFunction.
| - For production deployments, explicitly specify which tools to load rather than relying on defaults. This ensures consistent behavior across updates: | ||
|
|
||
| As above, this exposes only the specified Actor (`apify/my-actor`) as a tool. No other tools will be available. | ||
| `npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` |
There was a problem hiding this comment.
| `npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` | |
| `https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser` |
There was a problem hiding this comment.
Let's use remote server for production
| `npx @apify/actors-mcp-server --tools apify/web-scraper,apify/google-search-scraper` | ||
|
|
||
| :::caution Important recommendation | ||
| - Always use the latest version of the server by appending `@latest` to your npm commands. |
There was a problem hiding this comment.
| - Always use the latest version of the server by appending `@latest` to your npm commands. | |
| - For a local stdio server, always use the latest version of the server by appending `@latest` to your npm commands. |
There was a problem hiding this comment.
or you have the same sentence in the Local environment setup so, perhaps, we can skip it here. To focus on remote server only.
|
@TC-MO I really like the changes you did, would you have time to finish it this week 🙏🏻 . Before MPC summit in London? |
|
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? |
|
Yeah, that would be great! |
Stremline the prose for clarity & conciseness
Remove outdated SSE section
Restructure the content
Adjusted description in frontmatter