Skip to content

docs: align agent onboarding and MCP server pages with the live MCP server and skills - #3004

Open
marekh19 wants to merge 4 commits into
masterfrom
docs/agent-onboarding-mcp-coherence
Open

marekh19 wants to merge 4 commits into
masterfrom
docs/agent-onboarding-mcp-coherence

Conversation

@marekh19

@marekh19 marekh19 commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

The agent onboarding page, the MCP server page, and apify.com/agents.md disagreed on MCP defaults, cost caps, and the skills list.

Rebased on master. Most of the MCP tool reference here was superseded by #3006, which corrected the same table against @apify/actors-mcp-server@0.16.0 and went further (it caught the get-actor-log → get-actor-run-log rename this PR still had wrong). Those hunks are resolved in favour of master.

What remains:

  • Agent onboarding page: one remote MCP snippet with a link to the MCP page instead of a second stdio copy, Claude Desktop listed as a remote client, and cost caps matching the API reference (maxTotalChargeUsd for all pricing models, maxItems for pay-per-result).
  • MCP server page: the API token is a prerequisite only for stdio or Bearer auth, since the recommended remote connection uses OAuth.
  • Nine pages and two shared partials: replace the removed apify-sdk-integration skill with apify-integration-development.

Part of apify/apify-web#6547

@marekh19 marekh19 added the t-web Issues with this label are in the ownership of the web team. label Sep 21, 2026
@apify-service-account

apify-service-account commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

✅ Preview for this PR (commit 8af0a63d) is ready at https://pr-3004.preview.docs.apify.com (see action run).

@marekh19 marekh19 added this to the 149th sprint - Web team milestone Sep 21, 2026
@marekh19
marekh19 marked this pull request as ready for review September 21, 2026 10:10
@marekh19
marekh19 requested a review from webrdaniel September 21, 2026 10:10
# Conflicts:
#	sources/platform/integrations/ai/manus.md
#	sources/platform/integrations/ai/mcp.md
@marekh19
marekh19 force-pushed the docs/agent-onboarding-mcp-coherence branch from 117f4de to 8af0a63 Compare September 22, 2026 14:59
@marekh19

Copy link
Copy Markdown
Contributor Author

@marcel-rbro Hey Marcel, could you please check this? 🙏

@marekh19
marekh19 requested review from a team and honzajavorek and removed request for a team and marcel-rbro September 25, 2026 12:58
@TC-MO
TC-MO self-requested a review September 29, 2026 11:52

@TC-MO TC-MO left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry it took so long,

  • IIRC the Claude Desktop part about pasting a remote URL is factually wrong so requesting changes here
  • other issues are smaller:
    • wording issues
    • some crosslinking
    • reusing the partial when possible

#### Remote (recommended)

Works with Claude Code, Cursor, VS Code, GitHub Copilot, and other remote-capable clients.
Works with Claude Code, Claude Desktop, Cursor, VS Code, GitHub Copilot, and other remote-capable clients.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we sure about Claude Desktop being here? I thought Claude Desktop doesn't take a remote url in its JSON config. Remote servers are added as a custom connector.

Also, with the "Remote (recommended)" heading gone, nothing says this snippet is the remote server. Something like "To connect a remote-capable client such as…:" would label the steps.

Comment on lines 97 to +103
| Skill | Description |
| --- | --- |
| `apify-ultimate-scraper` | CLI-driven extraction using existing Actors for multi-step scraping and lead-generation workflows. |
| `apify-actor-development` | Full Actor lifecycle - template selection, development, local testing, and deployment with `apify push`. |
| `apify-actorization` | Converts existing JavaScript, TypeScript, Python, or CLI projects into Apify Actors. |
| `apify-generate-output-schema` | Generates dataset and key-value store schemas for existing Actors. |
| `apify-sdk-integration` | Integrates Actor execution into applications using the `apify-client` package. |
| `apify-integration-development` | Builds an official Apify integration for another product: workflow-automation apps, agent plugins, AI framework packages, or `apify-client` application code. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The five tables in claude-code-cli, cursor, kimi-code-cli, codex-app, and codex-cli duplicate _apify-plugin-skills.mdx. Could they import the partial instead? (Only difference is "CLI-driven" on the ultimate-scraper row.) Fine as a follow-up if you'd rather keep this PR to the rename.

@@ -48,7 +48,7 @@ The MCP server intentionally excludes two categories of Actors from search and e
Before connecting your AI to Apify, you'll need three things:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If token is now optional, then we don't need three things right?

- `maxItems` - cap the number of billed dataset items. Pay-per-result Actors only.
- `timeout` (seconds) - cap how long a single run can last.
- `maxTotalChargeUsd` - cap total run cost for pay-per-event Actors.
- `memory` (MB) - power of 2, minimum 128. Lower memory means lower cost per second.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for syntactic parallelism

Suggested change
- `memory` (MB) - power of 2, minimum 128. Lower memory means lower cost per second.
- `memory` (MB) - set memory as a power of 2, minimum 128. Lower memory means lower cost per second.

Comment on lines 261 to +267
| Skill | What it does |
| :--- | :--- |
| `apify-ultimate-scraper` | Routes web scraping requests to the right Actor for multi-step data pipelines |
| `apify-actor-development` | Guided workflow for building and deploying custom Actors |
| `apify-actorization` | Converts an existing project into an Apify Actor |
| `apify-generate-output-schema` | Auto-generates output schemas from Actor source code |
| `apify-sdk-integration` | Integrates Actor execution into applications using the `apify-client` package |
| `apify-integration-development` | Builds an official Apify integration for another product: workflow-automation apps, agent plugins, AI framework packages, or `apify-client` application code |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should this match the partial? If so, then just import the partial, if not keep it different.

- `maxTotalChargeUsd` - cap total run cost for pay-per-event Actors.
- `memory` (MB) - power of 2, minimum 128. Lower memory means lower cost per second.

Over MCP, pass the same caps in the `callOptions` argument of `call-actor`. Never put them in the Actor input, where they are ignored or rejected.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This lands in the Cost controls admonition before the page introduces the MCP server, and call-actor isn't linked. Could it move to the MCP server section, with a link to /integrations/mcp#available-tools? Also, "ignored or rejected" depends on the Actor's input schema does it not?


- _An Apify account_ - Sign up for an Apify account, if you don't have one.
- _Apify API token_ - Get your API token from the **API & Integrations** section in [Apify Console](https://console.apify.com/settings/integrations). This token authorizes the MCP server to run Actors on your behalf. Make sure to keep it secure.
- _Apify API token_ - Only needed for the [local stdio server](#local-stdio) or the Bearer token option. The recommended remote connection signs you in with OAuth instead. Get your token from the **API & Integrations** section in [Apify Console](https://console.apify.com/settings/integrations) and keep it secure.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Bearer token option shows up before the Bearer tab is introduced. Worth linking it to #streamable-http-with-oauth-recommended?

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

t-web Issues with this label are in the ownership of the web team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants