{
"canonical_name": "apify/apify-mcp-server",
"compilation_id": "pack_0de0b06bc3044e738a154e3e62fc163d",
"created_at": "2026-05-22T10:54:21.455904+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx @apify/actors-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx @apify/actors-mcp-server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_3bb21aa07db9465eaa806d957e5cc863"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_1b4559d83fe8d98c9f9eea922165b108",
"canonical_name": "apify/apify-mcp-server",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/apify/apify-mcp-server",
"slug": "apify-mcp-server",
"source_packet_id": "phit_5304e61c3cfa454cb3b54c0cde53dddf",
"source_validation_id": "dval_3c0090282d844cdcb2eaae0b56d117e6"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 166,
"github_stars": 1226,
"one_liner_en": "The Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.",
"one_liner_zh": "The Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.",
"primary_category": {
"category_id": "tool-integrations",
"name_zh": "工具连接与集成",
"name_en": "Tool Integrations",
"confidence": "high",
"reason": "semantic truth gate fallback rework"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "apify-mcp-server",
"title_zh": "apify-mcp-server 能力包",
"visible_tags": [
{
"type": "product_domain",
"label_zh": "工具连接与集成",
"label_en": "Tool Integrations",
"tag_id": "product_domain-tool-integrations",
"source": "semantic_truth_gate_rework"
},
{
"type": "user_job",
"label_zh": "Model Context Protocol",
"label_en": "Model Context Protocol",
"tag_id": "user_job-model-context-protocol",
"source": "semantic_truth_gate_rework"
},
{
"type": "core_capability",
"label_zh": "MCP Server/Client",
"label_en": "MCP Server/Client",
"tag_id": "core_capability-mcp-server-client",
"source": "semantic_truth_gate_rework"
},
{
"type": "workflow_pattern",
"label_zh": "宿主配置",
"label_en": "Host Configuration",
"tag_id": "workflow_pattern-host-configuration",
"source": "semantic_truth_gate_rework"
},
{
"type": "selection_signal",
"label_zh": "权限边界",
"label_en": "Permission Boundary",
"tag_id": "selection_signal-permission-boundary",
"source": "semantic_truth_gate_rework"
}
]
},
"packet_id": "phit_5304e61c3cfa454cb3b54c0cde53dddf",
"page_model": {
"artifacts": {
"artifact_slug": "apify-mcp-server",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx @apify/actors-mcp-server",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/apify/apify-mcp-server#readme",
"verified": true
}
],
"display_tags": [
"Tool Integrations",
"Model Context Protocol",
"MCP Server/Client",
"Host Configuration",
"Permission Boundary"
],
"eyebrow": "Tool Integrations",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Do not include the rag web browser when ?payment=x402",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：feat(telemetry): track tool result size in bytes",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：feat: Add structured output to remaining storage tools",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：feat: migrate direct actor tools to canonical RunResponse shape",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：test: Consolidate duplicated MCP server test fixtures",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：feat: Dataset tools correctness and coverage",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：chore: Add mixpanel analytics for storage tools + error rates",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 30,
"forks": 166,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1226
},
"source_url": "https://github.com/apify/apify-mcp-server",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Model Context Protocol integration pack focused on server/client setup, host configuration, tool permissions, and rollback boundaries.",
"title": "apify-mcp-server 能力包",
"trial_prompt": "# apify-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for apify/apify-mcp-server.\n\nProject:\n- Name: apify-mcp-server\n- Repository: https://github.com/apify/apify-mcp-server\n- Summary: The Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.\n- Host target: mcp_host\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: The Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. architecture-details: Core Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. tool-system: Tool System. Produce one small intermediate artifact and wait for confirmation.\n4. actor-tools: Actor Tools. Produce one small intermediate artifact and wait for confirmation.\n5. payments-overview: Agentic Payments System. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/apify/apify-mcp-server\n- https://github.com/apify/apify-mcp-server#readme\n- .claude/skills/bug-triage/SKILL.md\n- .claude/skills/dig/SKILL.md\n- README.md\n- package.json\n- src/const.ts\n- src/mcp/server.ts\n- src/mcp/actors.ts\n- src/mcp/client.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: feat(telemetry): track tool result size in bytes（https://github.com/apify/apify-mcp-server/issues/838）；github/github_issue: chore(core): collapse array indices in dataset fields to prevent nextSte（https://github.com/apify/apify-mcp-server/issues/894）；github/github_issue: Remove the flat-fields back-compat shim from `_meta.x402` once all consu（https://github.com/apify/apify-mcp-server/issues/892）；github/github_issue: Do not include the rag web browser when ?payment=x402（https://github.com/apify/apify-mcp-server/issues/875）；github/github_issue: design: Calibrate get-dataset-schema output detail（https://github.com/apify/apify-mcp-server/issues/882）；github/github_issue: refactor: Extract storage tool helpers（https://github.com/apify/apify-mcp-server/issues/890）；github/github_issue: feat: Add structured output to remaining storage tools（https://github.com/apify/apify-mcp-server/issues/884）；github/github_issue: Perf: `search-actors` tools returns huuuge `inputFields` object（https://github.com/apify/apify-mcp-server/issues/888）；github/github_issue: [Bug]: Inconsistent `search-actors` schema and results（https://github.com/apify/apify-mcp-server/issues/889）；github/github_issue: fix: Allow calling MCP server actors in normal (one-shot) mode（https://github.com/apify/apify-mcp-server/issues/857）；github/github_issue: chore: Add mixpanel analytics for storage tools + error rates（https://github.com/apify/apify-mcp-server/issues/887）；github/github_issue: tools/list response contains `type: \"unknown\"` in an input schema — reje（https://github.com/apify/apify-mcp-server/issues/738）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "feat(telemetry): track tool result size in bytes",
"url": "https://github.com/apify/apify-mcp-server/issues/838"
},
{
"kind": "github_issue",
"source": "github",
"title": "chore(core): collapse array indices in dataset fields to prevent nextSte",
"url": "https://github.com/apify/apify-mcp-server/issues/894"
},
{
"kind": "github_issue",
"source": "github",
"title": "Remove the flat-fields back-compat shim from `_meta.x402` once all consu",
"url": "https://github.com/apify/apify-mcp-server/issues/892"
},
{
"kind": "github_issue",
"source": "github",
"title": "Do not include the rag web browser when ?payment=x402",
"url": "https://github.com/apify/apify-mcp-server/issues/875"
},
{
"kind": "github_issue",
"source": "github",
"title": "design: Calibrate get-dataset-schema output detail",
"url": "https://github.com/apify/apify-mcp-server/issues/882"
},
{
"kind": "github_issue",
"source": "github",
"title": "refactor: Extract storage tool helpers",
"url": "https://github.com/apify/apify-mcp-server/issues/890"
},
{
"kind": "github_issue",
"source": "github",
"title": "feat: Add structured output to remaining storage tools",
"url": "https://github.com/apify/apify-mcp-server/issues/884"
},
{
"kind": "github_issue",
"source": "github",
"title": "Perf: `search-actors` tools returns huuuge `inputFields` object",
"url": "https://github.com/apify/apify-mcp-server/issues/888"
},
{
"kind": "github_issue",
"source": "github",
"title": "[Bug]: Inconsistent `search-actors` schema and results",
"url": "https://github.com/apify/apify-mcp-server/issues/889"
},
{
"kind": "github_issue",
"source": "github",
"title": "fix: Allow calling MCP server actors in normal (one-shot) mode",
"url": "https://github.com/apify/apify-mcp-server/issues/857"
},
{
"kind": "github_issue",
"source": "github",
"title": "chore: Add mixpanel analytics for storage tools + error rates",
"url": "https://github.com/apify/apify-mcp-server/issues/887"
},
{
"kind": "github_issue",
"source": "github",
"title": "tools/list response contains `type: \"unknown\"` in an input schema — reje",
"url": "https://github.com/apify/apify-mcp-server/issues/738"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "Tool Integrations",
"desc": "Model Context Protocol integration pack focused on server/client setup, host configuration, tool permissions, and rollback boundaries.",
"effort": "安装已验证",
"forks": 166,
"icon": "link",
"name": "apify-mcp-server 能力包",
"risk": "可发布",
"slug": "apify-mcp-server",
"stars": 1226,
"tags": [
"Tool Integrations",
"Model Context Protocol",
"MCP Server/Client",
"Host Configuration",
"Permission Boundary"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/apify/apify-mcp-server Project Manual\n\nGenerated on: 2026-05-22 10:52:06 UTC\n\n## Table of Contents\n\n- [Project Overview](#overview)\n- [Core Architecture](#architecture-details)\n- [Transport Layer](#transport-layer)\n- [Tool System](#tool-system)\n- [Actor Tools](#actor-tools)\n- [Storage Access Tools](#storage-tools)\n- [Agentic Payments System](#payments-overview)\n- [Widget System](#widget-system)\n- [UI Components Library](#ui-components)\n- [Development Setup](#development-setup)\n\n\n\n## Project Overview\n\n### Related Pages\n\nRelated topics: [Core Architecture](#architecture-details), [Tool System](#tool-system)\n\n\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n- [manifest.json](https://github.com/apify/apify-mcp-server/blob/main/manifest.json)\n- [CONTRIBUTING.md](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)\n- [DEVELOPMENT.md](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)\n- [res/algolia.md](https://github.com/apify/apify-mcp-server/blob/main/res/algolia.md)\n- [res/mcp_resources_analysis.md](https://github.com/apify/apify-mcp-server/blob/main/res/mcp_resources_analysis.md)\n- [res/index.md](https://github.com/apify/apify-mcp-server/blob/main/res/index.md)\n\n\n# Project Overview\n\nApify MCP Server is a Model Context Protocol (MCP) server that provides AI assistants with access to Apify's platform capabilities. The server acts as a bridge between AI models and Apify's cloud infrastructure, enabling AI assistants to search and interact with Actors, documentation, and web content.\n\nSource: [README.md:1]()\n\n## What is the Apify MCP Server?\n\nThe Apify MCP Server implements the MCP specification to expose Apify platform features as tools that AI assistants can invoke. This allows AI models to:\n\n- Search and discover Actors on the Apify platform\n- Fetch detailed information about specific Actors\n- Search Apify and Crawlee documentation\n- Execute web scraping and automation tasks through the RAG web browser tool\n\nSource: [README.md:22-30]()\n\n## Architecture Overview\n\nThe project follows a monorepo structure with the following key directories:\n\n| Directory | Purpose |\n|-----------|---------|\n| `src/` | Core MCP server implementation |\n| `src/web/` | React UI widgets for MCP Apps (ChatGPT integration) |\n| `tests/unit/` | Unit tests for individual modules |\n| `tests/integration/` | Integration tests for full server functionality |\n| `res/` | Technical documentation and analysis |\n\nSource: [DEVELOPMENT.md:1-20]()\n\n### Server Components\n\nThe MCP server is built around the `ActorsMcpServer` class in `src/mcp/server.ts`, which wraps the low-level MCP `Server` API. The server exposes tools through request handlers for tool listing and tool calling.\n\n```mermaid\ngraph TD\n A[AI Assistant] -->|MCP Protocol| B[ActorsMcpServer]\n B -->|Tool Requests| C[Tool Registry]\n C -->|Actors Tools| D[Actor Discovery & Execution]\n C -->|Docs Tools| E[Algolia Search API]\n C -->|RAG Tools| F[RAG Web Browser]\n D -->|API Calls| G[Apify API]\n E -->|Search Queries| H[Algolia]\n F -->|Browser Actions| I[Crawlee/Puppeteer]\n```\n\nSource: [res/mcp_resources_analysis.md:1-15]()\n\n## Available Tools\n\nThe server provides the following tool categories and individual tools:\n\n### Default Tools\n\nWhen no query parameters are provided, the MCP server loads these tools by default:\n\n| Tool Category | Description |\n|---------------|-------------|\n| `actors` | Search and discover Actors on the Apify platform |\n| `docs` | Search Apify and Crawlee documentation |\n| `apify/rag-web-browser` | RAG-enabled web browsing for AI consumption |\n\nSource: [README.md:48-52]()\n\n### Tool Configuration\n\nTools can be configured via query parameters or command-line flags:\n\n| Configuration Method | Example |\n|----------------------|---------|\n| Hosted server URL | `https://mcp.apify.com?tools=actors,docs,apify/rag-web-browser` |\n| CLI flag | `npx @apify/actors-mcp-server --tools actors,docs` |\n| Minimal (single Actor) | `https://mcp.apify.com?tools=apify/my-actor` |\n\nSource: [README.md:55-75]()\n\n### Unauthenticated Access\n\nThe hosted server allows access without an API token when only specific tools are requested:\n\n| Allowed Tool | Description |\n|--------------|-------------|\n| `search-actors` | Search Actors without authentication |\n| `fetch-actor-details` | Get Actor details without authentication |\n| `search-apify-docs` | Search Apify docs without authentication |\n| `fetch-apify-docs` | Get doc pages without authentication |\n\nSource: [README.md:33-35]()\n\n## Deployment Modes\n\nThe Apify MCP Server supports multiple deployment configurations:\n\n### HTTP Streamable Mode\n\nRuns as an HTTP server compatible with the streamable HTTP transport:\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nexport APIFY_META_ORIGIN=STANDBY\napify run -p\n```\n\nThe server exposes endpoints at `http://localhost:3001` by default.\n\nSource: [README.md:14-20]()\n\n### Standard Input/Output (stdio) Mode\n\nRuns as a subprocess communicating via stdin/stdout, suitable for local development and debugging:\n\n```bash\nnpx @modelcontextprotocol/inspector node ./dist/stdio.js\n```\n\nSource: [README.md:22-30]()\n\n### Claude Desktop Integration\n\nThe server can be configured as a Claude Desktop MCP tool:\n\n```json\n{\n \"mcpServers\": {\n \"apify\": {\n \"command\": \"node\",\n \"args\": [\"${__dirname}/dist/stdio.js\", \"--tools\", \"${user_config.tools}\"],\n \"env\": {\n \"APIFY_TOKEN\": \"${user_config.apify_token}\"\n }\n }\n }\n}\n```\n\nSource: [manifest.json:35-45]()\n\n## User Configuration\n\nThe server accepts the following user configuration options:\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `apify_token` | string | Yes* | - | Apify API token from console.apify.com |\n| `tools` | string | No | `actors,docs,apify/rag-web-browser` | Comma-separated list of tool categories or specific Actors |\n\n*Required unless using unauthenticated access with specific tools.\n\nSource: [manifest.json:47-65]()\n\n## Documentation Search Architecture\n\nThe docs tool integrates with Algolia to provide search across Apify and Crawlee documentation:\n\n```mermaid\ngraph LR\n A[Search Query] -->|Algolia API| B[Algolia Index]\n B -->|Results| C[processAlgoliaResponse]\n C -->|URLs with fragments| D[LLM Response]\n \n E[Fetch Tool] -->|URL Request| F[Documentation Site]\n F -->|HTML Content| E\n```\n\n### Algolia Response Processing\n\nThe server processes Algolia responses differently based on the documentation source:\n\n| Source | URL Fragments | Content Field |\n|--------|---------------|---------------|\n| Apify docs | Supported | Always populated |\n| Crawlee docs | Not supported | Not available |\n\nSource: [res/algolia.md:1-50]()\n\n### URL Fragment Handling\n\nThe server embeds page anchors directly in returned URLs for section-specific navigation:\n\n```typescript\n// Returns ready-to-use URLs with anchors\n{ url: \"https://docs.apify.com/actors#build-actors\", content: \"...\" }\n```\n\nThis approach simplifies the LLM's ability to navigate to specific sections without complex URL reconstruction logic.\n\nSource: [res/algolia.md:55-70]()\n\n## MCP Resources\n\nThe server exposes MCP resources for specific use cases:\n\n| Resource Type | URI Pattern | Description |\n|---------------|-------------|-------------|\n| Skyfire usage guide | `file://readme.md` | Enabled when `skyfireMode` is true |\n| UI widgets | `ui://widget/*` | React widgets for OpenAI MCP Apps |\n\nSource: [res/mcp_resources_analysis.md:15-30]()\n\n## Development Setup\n\n### Prerequisites\n\n| Requirement | Version |\n|-------------|---------|\n| Node.js | >=20.0.0 |\n| pnpm | 11+ |\n\nSource: [DEVELOPMENT.md:25-30]()\n\n### Installation\n\n```bash\ncorepack enable # enables pnpm via corepack\npnpm install # installs root + src/web workspace packages\n```\n\nSource: [DEVELOPMENT.md:30-35]()\n\n### Building\n\n```bash\npnpm run build\n```\n\nBuilds the TypeScript source to JavaScript in the `dist/` directory.\n\nSource: [DEVELOPMENT.md:60-65]()\n\n## Testing\n\nThe project maintains multiple testing layers:\n\n| Test Layer | Command | Coverage |\n|------------|---------|----------|\n| Unit tests | `pnpm run test:unit` | Individual modules in isolation |\n| Integration tests | `pnpm run test:integration` | Full server over all transports |\n| LLM evals | CI only (apply `validated` label) | Multiple AI models via OpenRouter |\n\nSource: [DEVELOPMENT.md:8-20]()\n\n### Test Configuration\n\n| Environment Variable | Purpose |\n|---------------------|---------|\n| `APIFY_TOKEN` | Required for integration tests |\n| `PHOENIX_*` | Phoenix evaluation secrets |\n| `OPENROUTER_*` | OpenRouter API secrets |\n\nSource: [DEVELOPMENT.md:15-20]()\n\n## UI Widgets\n\nFor OpenAI MCP Apps integration, the server supports React-based UI widgets located in `src/web/`. Widgets are rendered based on tool output and require the server to run in UI mode:\n\n```\nhttps://mcp.apify.com?ui=true\n```\n\nOr set the environment variable `UI_MODE=true`.\n\nSource: [DEVELOPMENT.md:50-55]()\n\n### Widget Configuration\n\nWidgets must use the Apify design system tokens:\n\n| Property | Token Pattern | Example |\n|----------|---------------|---------|\n| Text color | `theme.color.{cat}.{prop}` | `theme.color.neutral.text` |\n| Background | `theme.color.{cat}.{prop}` | `theme.color.primary.background` |\n| Spacing | `theme.space.space{N}` | `theme.space.space16` |\n| Border radius | `theme.radius.radius{N}` | `theme.radius.radius8` |\n\nSource: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md:1-20]()\n\n## Contribution Guidelines\n\nThe project follows conventional commits for versioning and changelog generation:\n\n### Branch Naming\n\n```text\nfeat/add-dataset-tool\nfix/connection-timeout\nchore/update-dependencies\n```\n\n### Commit Format\n\n```\n(): \n\nTypes: feat, fix, refactor, chore, docs, test, etc.\n```\n\nBreaking changes are indicated with `!` after the scope.\n\nSource: [CONTRIBUTING.md:1-30]()\n\n## Compatibility\n\n| Platform | Claude Desktop Version | Node.js |\n|----------|----------------------|---------|\n| macOS (darwin) | >=0.2.16 | >=20.0.0 |\n| Windows (win32) | >=0.2.16 | >=20.0.0 |\n| Linux | >=0.2.16 | >=20.0.0 |\n\nSource: [manifest.json:20-28]()\n\n## Repository Structure\n\nThe codebase is split across two repositories:\n\n| Repository | Purpose |\n|------------|---------|\n| `apify-mcp-server` (this repo) | Core MCP logic and public code |\n| `apify-mcp-server-internal` | Hosted server deployment |\n\nChanges must be synchronized between both repositories. Canary releases are created by adding the `beta` tag to a PR branch.\n\nSource: [README.md:38-42]()\n\n---\n\n\n\n## Core Architecture\n\n### Related Pages\n\nRelated topics: [Project Overview](#overview), [Transport Layer](#transport-layer)\n\n\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n- [src/mcp/actors.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/actors.ts)\n- [src/mcp/client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/client.ts)\n- [src/mcp/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/resources/resource_service.ts)\n- [src/types.ts](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts)\n- [src/mcp/proxy.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/proxy.ts)\n\n\n# Core Architecture\n\nThe Apify MCP Server implements a Model Context Protocol (MCP) server that exposes Apify platform capabilities as tools for Large Language Models (LLMs). The architecture uses the low-level MCP `Server` SDK with a custom tool management system, supporting both stdio and HTTP Streamable transports.\n\n## System Overview\n\nThe server acts as a bridge between LLMs and the Apify platform, enabling AI assistants to:\n\n- Search and discover Actors on the Apify platform\n- Execute Actors programmatically\n- Access Apify documentation\n- Manage Actor runs and retrieve results\n- Proxy external MCP servers through Actorized deployments\n\nSource: [src/mcp/server.ts:1-50](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n```mermaid\ngraph TD\n subgraph \"Transport Layer\"\n STDIO[stdio.ts Standard I/O]\n HTTP[dev_server.ts HTTP Streamable]\n end\n \n subgraph \"Core Server\"\n AMS[ActorsMcpServer]\n TM[Tool Manager Map<string, ToolEntry>]\n TS[TaskStore]\n AS[ActorStore]\n end\n \n subgraph \"Tool Registry\"\n HT[Helper Tools]\n AT[Actor Tools]\n AMT[Actor-MCP Proxy Tools]\n end\n \n subgraph \"External Services\"\n APIFY[Apify API]\n APIClient[ApifyClient]\n end\n \n STDIO --> AMS\n HTTP --> AMS\n AMS --> TM\n AMS --> TS\n AMS --> AS\n TM --> HT\n TM --> AT\n TM --> AMT\n AMS --> APIClient\n APIClient --> APIFY\n```\n\n## High-Level Component Architecture\n\n### ActorsMcpServer (Central Coordinator)\n\nThe `ActorsMcpServer` class is the core component that orchestrates all MCP functionality:\n\n| Property | Type | Purpose |\n|----------|------|---------|\n| `server` | `Server` | Low-level MCP SDK server instance |\n| `tools` | `Map` | Tool registry for all registered tools |\n| `taskStore` | `TaskStore` | Tracks running and completed tasks |\n| `actorStore` | `ActorStore` | Caches Actor metadata and input schemas |\n| `serverMode` | `ServerMode` | Resolved server mode (default/apps) |\n| `options` | `ActorsMcpServerOptions` | Server configuration options |\n\nSource: [src/mcp/server.ts:280-320](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n### Tool Entry Types\n\nThe server manages three distinct tool types defined in the discriminated union:\n\n```typescript\ntype ToolEntry = HelperTool | ActorTool | ActorMcpTool;\n```\n\n| Tool Type | Type Discriminator | Purpose | Source |\n|-----------|-------------------|---------|--------|\n| `HelperTool` | `type: 'internal'` | Built-in server tools (search, docs) | [src/types.ts:135-145](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts) |\n| `ActorTool` | `type: 'actor'` | Dynamic Actor-based tools | [src/types.ts:147-153](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts) |\n| `ActorMcpTool` | `type: 'actor-mcp'` | External MCP server proxy via Actor | [src/types.ts:155-162](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts) |\n\nSource: [src/types.ts:130-175](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts)\n\n## Transport Architecture\n\nThe server supports two transport mechanisms, selected based on deployment context:\n\n### Stdio Transport\n\nUsed for local CLI clients and the MCP Inspector. Communication occurs through standard input/output streams.\n\nSource: [src/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index.ts)\n\n### HTTP Streamable Transport\n\nUsed for hosted deployments at `mcp.apify.com`. Enables remote client connections with streaming response support.\n\nSource: [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n| Transport | Use Case | Entry Point |\n|-----------|----------|-------------|\n| stdio | Local CLI, MCP Inspector | `stdio.ts` |\n| HTTP Streamable | Hosted server, remote clients | `dev_server.ts` |\n\n## Request Handler Architecture\n\nThe server uses low-level MCP SDK request handlers for all protocol operations:\n\n### Handler Registration Pattern\n\n```typescript\nserver.setRequestHandler(ListToolsRequestSchema, async () => { ... });\nserver.setRequestHandler(CallToolRequestSchema, async (request) => { ... });\nserver.setRequestHandler(ListResourcesRequestSchema, async () => { ... });\nserver.setRequestHandler(ReadResourceRequestSchema, async (request) => { ... });\n```\n\nSource: [src/mcp/server.ts:200-250](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n### Central Tool Dispatcher\n\nAll tool calls flow through a central dispatcher that routes based on tool type:\n\n```mermaid\ngraph LR\n A[CallTool Request] --> B{Extract toolName}\n B --> C{Lookup in tools Map}\n C -->|HelperTool| D[Execute call function]\n C -->|ActorTool| E[Call Apify API]\n C -->|ActorMcpTool| F[Proxy to Actor-MCP]\n D --> G[Return result]\n E --> G\n F --> G\n```\n\nSource: [src/mcp/server.ts:400-500](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Tool Lifecycle Management\n\n### Dynamic Tool Loading\n\nActors are loaded as tools through the `loadActorsAsTools()` method:\n\n1. Fetch Actor list from Apify API or configured Actor IDs\n2. Transform Actor metadata into `ActorTool` entries\n3. Upsert tools into the registry Map\n4. Send `notifications/tools/list_changed` to connected clients\n\nSource: [src/mcp/actors.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/actors.ts)\n\n### Tool Registration Flow\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server as ActorsMcpServer\n participant API as Apify API\n participant Store as tools Map\n \n Client->>Server: initialize (capabilities)\n Server->>Server: resolveServerMode()\n Server->>API: fetchActors() / getActorDetails()\n API-->>Server: Actor metadata\n Server->>Store: upsertTools()\n Server-->>Client: tools/list response\n Client->>Server: notifications/tools/list_changed\n```\n\n## Server Mode System\n\nThe server supports automatic mode detection based on client capabilities:\n\n| Mode | Trigger | Behavior |\n|------|---------|----------|\n| `default` | Non-MCP Apps clients | Standard tool responses |\n| `apps` | MCP Apps clients (`uiMode === 'openai'`) | Enhanced responses with widget metadata |\n\nSource: [src/mcp/server.ts:300-340](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n### Mode Auto-Detection\n\nThe `serverMode` property transitions from `'auto'` to either `'default'` or `'apps'` during the `initialize` request handler:\n\n```typescript\n// Preliminary value at construction\npublic serverMode: ServerMode;\n\n// Finalized inside initialize handler\nprivate serverModeResolved: boolean;\n```\n\nSource: [src/mcp/server.ts:310-325](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Resource System\n\nThe server implements MCP resources for UI widgets and documentation:\n\n### Resource Types\n\n| Resource Type | URI Pattern | Condition | Source |\n|---------------|-------------|-----------|--------|\n| Skyfire Guide | `file://readme.md` | `skyfireMode === true` | [src/mcp/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/resources/resource_service.ts) |\n| UI Widgets | `ui://widget/*.html` | `uiMode === 'openai'` | [src/mcp/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/resources/resource_service.ts) |\n\n### Resource Handler Implementation\n\n```typescript\nreturn {\n listResources,\n readResource,\n listResourceTemplates: async () => ({ resourceTemplates: [] }),\n};\n```\n\nSource: [src/mcp/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/resources/resource_service.ts)\n\n## Actor-MCP Proxy Architecture\n\nExternal MCP servers can be proxied through the Apify platform using the `ActorMcpTool` type:\n\n```mermaid\ngraph LR\n subgraph \"This Server\"\n A[ActorMcpTool] --> B[proxy.ts]\n end\n \n subgraph \"Apify Platform\"\n B -->|callActor| C[Actor Container]\n end\n \n subgraph \"Remote MCP Server\"\n C -->|HTTP| D[External Server]\n D -->|MCP Response| C\n end\n \n C -->|Actor Result| B\n```\n\nSource: [src/mcp/proxy.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/proxy.ts)\n\n## Task Management\n\n### TaskStore\n\nThe `TaskStore` class manages long-running task execution:\n\n| Method | Purpose |\n|--------|---------|\n| `createTask()` | Initialize a new task |\n| `updateTask()` | Update task status/progress |\n| `getTask()` | Retrieve task details |\n| `listTasks()` | List all tasks |\n\nSource: [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n### Progress Tracking\n\nLong-running operations support progress notifications via `createProgressTracker`:\n\n```typescript\nconst tracker = createProgressTracker(taskId, totalSteps);\ntracker.report(progress, total, message);\n```\n\nSource: [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Client Configuration\n\n### ApifyClient Integration\n\nThe server uses the Apify JavaScript client for API communication:\n\n```typescript\nconst apifyClient = new ApifyClient({\n token: apifyToken,\n});\n```\n\nSource: [src/mcp/client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/client.ts)\n\n### Token Propagation\n\n| Location | Mechanism |\n|----------|------------|\n| HTTP Headers | `Authorization: Bearer ` |\n| MCP Meta | `_meta.apifyToken` in tool call |\n\nSource: [src/mcp/server.ts:630-650](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Configuration Options\n\nThe `ActorsMcpServerOptions` interface defines server configuration:\n\n| Option | Type | Default | Purpose |\n|--------|------|---------|---------|\n| `apifyToken` | `string` | Required | Apify API authentication |\n| `tools` | `string \\| string[]` | `default` | Tool categories/Actors to load |\n| `serverMode` | `ServerModeOption` | `'auto'` | Server mode override |\n| `skyfireMode` | `boolean` | `false` | Enable Skyfire-specific resources |\n| `uiMode` | `UiMode` | `'default'` | UI response format |\n\nSource: [src/mcp/server.ts:200-280](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Capability Advertisement\n\nThe server advertises the following MCP capabilities during initialization:\n\n```typescript\ncapabilities: {\n logging: {},\n prompts: { listChanged: false },\n resources: options.skyfireMode ? { listChanged: false } : undefined,\n tools: { listChanged: true },\n}\n```\n\nSource: [src/mcp/server.ts:210-218](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Entry Points\n\n| Entry Point | Transport | File |\n|-------------|-----------|------|\n| `dist/stdio.js` | stdio | `src/stdio.ts` |\n| `dist/index.js` (HTTP) | Streamable HTTP | `src/dev_server.ts` |\n\nSource: [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## Transport Layer\n\n### Related Pages\n\nRelated topics: [Core Architecture](#architecture-details), [Development Setup](#development-setup)\n\n\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [src/stdio.ts](https://github.com/apify/apify-mcp-server/blob/main/src/stdio.ts)\n- [src/server_card.ts](https://github.com/apify/apify-mcp-server/blob/main/src/server_card.ts)\n- [src/index_internals.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index_internals.ts)\n- [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n- [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n- [src/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index.ts)\n\n\n# Transport Layer\n\nThe Apify MCP Server implements a dual-transport architecture that supports both local command-line clients and remote HTTP clients. This design allows the same core server logic to operate in different deployment scenarios while maintaining a consistent MCP protocol implementation.\n\n## Overview\n\nThe transport layer handles the communication between MCP clients and the `ActorsMcpServer` core. The server supports two primary transport mechanisms:\n\n| Transport Mode | Entry Point | Use Case | Protocol |\n|---------------|-------------|----------|----------|\n| **Stdio** | `stdio.ts` | Local CLI clients, Claude Code, MCP Inspector | Standard I/O via process stdin/stdout |\n| **HTTP Streamable** | `dev_server.ts` | Remote clients, hosted deployment at mcp.apify.com | Streamable HTTP with Server-Sent Events |\n\nSource: [src/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index.ts) · [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n\n## Architecture Diagram\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[CLI Client]\n HTTP_CLIENT[HTTP Client]\n MCP_INSPECTOR[MCP Inspector]\n end\n\n subgraph \"Transport Layer\"\n STDIO[Stdio Transport stdio.ts]\n HTTP[HTTP Transport dev_server.ts]\n WEBSOCKET[WebSocket Support mcp/server.ts]\n end\n\n subgraph \"Core Server\"\n SERVER[ActorsMcpServer server.ts]\n TOOLS[Tool Handlers]\n RESOURCES[Resource Handlers]\n TASKS[Task Store]\n end\n\n CLI --> STDIO\n HTTP_CLIENT --> HTTP\n MCP_INSPECTOR -->|stdio mode| STDIO\n MCP_INSPECTOR -->|http mode| HTTP\n\n STDIO --> SERVER\n HTTP --> SERVER\n WEBSOCKET --> SERVER\n\n SERVER --> TOOLS\n SERVER --> RESOURCES\n SERVER --> TASKS\n```\n\n## Stdio Transport\n\nThe Standard I/O transport is designed for local development and CLI-based clients. It communicates via process stdin and stdout using JSON-RPC messages.\n\n### Entry Point\n\nThe stdio transport is initialized in `src/stdio.ts`:\n\n```typescript\nimport { createStdioServer } from '@modelcontextprotocol/sdk/server/stdio';\n\n// Server initialization with transport\nconst server = new ActorsMcpServer(options);\nconst transport = createStdioServer();\nawait server.connect(transport);\n```\n\nSource: [src/stdio.ts](https://github.com/apify/apify-mcp-server/blob/main/src/stdio.ts)\n\n### Connection Flow\n\n```mermaid\nsequenceDiagram\n participant Client as MCP Client\n participant Stdio as Stdio Transport\n participant Server as ActorsMcpServer\n\n Note over Client,Stdio: Process startup\n Stdio->>Server: Initialize connection\n Server->>Stdio: MCP handshake (initialize)\n Client->>Stdio: Initialize response\n Stdio->>Server: Handshake complete\n\n loop Message Loop\n Client->>Stdio: JSON-RPC Request\n Stdio->>Server: Forward request\n Server->>Server: Process tool/resource/task\n Server->>Stdio: JSON-RPC Response\n Stdio->>Client: Response output\n end\n\n Note over Client,Stdio: Process termination\n Client->>Stdio: SIGINT\n Stdio->>Server: Cleanup\n```\n\n### Configuration\n\nThe stdio transport inherits server configuration from environment variables and constructor options:\n\n| Parameter | Source | Description |\n|-----------|--------|-------------|\n| `APIFY_TOKEN` | Environment | Apify API authentication token |\n| `serverMode` | Constructor | `\"default\"`, `\"apps\"`, or `\"auto\"` |\n| `skyfireMode` | Constructor | Enables Skyfire usage guide resource |\n\nSource: [src/stdio.ts](https://github.com/apify/apify-mcp-server/blob/main/src/stdio.ts) · [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## HTTP Streamable Transport\n\nThe HTTP transport enables remote client connections using the MCP Streamable HTTP specification. This is used for the hosted deployment at `mcp.apify.com`.\n\n### Server Implementation\n\nThe HTTP server is implemented using Express in `src/dev_server.ts`:\n\n```typescript\nimport express from 'express';\nimport { createServer } from 'http';\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/http';\n\nconst app = express();\nconst server = createServer(app);\n\n// Streamable HTTP transport with session management\nconst transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: () => crypto.randomUUID(),\n onSession: initializeSession,\n});\n```\n\nSource: [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n\n### HTTP Endpoints\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/mcp` | POST | JSON-RPC requests (tools, resources, tasks) |\n| `/mcp` | GET | Server-Sent Events for notifications |\n| `/health` | GET | Health check endpoint |\n\nSource: [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n\n### Session Management\n\n```mermaid\ngraph LR\n A[Client] -->|1. POST /mcp| B{Has Session ID?}\n B -->|No| C[Create New Session]\n B -->|Yes| D[Find Existing Session]\n C --> E[Initialize MCP]\n D --> E\n E --> F[Store in Map]\n F --> G[Process Request]\n G --> H[Return Response]\n```\n\nThe transport uses UUID-based session identifiers to maintain separate server instances per client connection.\n\nSource: [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n\n## Server Card\n\nThe `ServerCard` component provides metadata and capability information about the MCP server for discovery and documentation purposes.\n\n### ServerCard Structure\n\n```typescript\nexport interface ServerCard {\n name: string;\n version: string;\n description: string;\n homepageUrl: string;\n repositoryUrl: string;\n documentationUrl: string;\n capabilities: ServerCapabilities;\n auth?: AuthConfig;\n configSchema?: Record;\n}\n```\n\nSource: [src/server_card.ts](https://github.com/apify/apify-mcp-server/blob/main/src/server_card.ts)\n\n### Capability Declaration\n\nThe server advertises its capabilities during the MCP `initialize` handshake:\n\n```typescript\nconst capabilities = {\n tools: { listChanged: true },\n tasks: { list: true, cancel: true, requests: { tools: { call: true } } },\n resources: {},\n prompts: {},\n logging: {},\n};\n```\n\nSource: [src/mcp/server.ts:146](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts#L146)\n\n## Internal Exports\n\nThe `index_internals.ts` module exposes internal components for testing and advanced usage scenarios:\n\n| Export | Type | Purpose |\n|--------|------|---------|\n| `ActorsMcpServer` | Class | Core MCP server implementation |\n| `createResourceService` | Function | Resource service factory |\n| `ToolEntry` | Type | Union type for all tool variants |\n| `ServerMode` | Enum | Server operating mode |\n\nSource: [src/index_internals.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index_internals.ts)\n\n## Server Modes\n\nThe transport layer operates differently based on the selected server mode:\n\n| Mode | Description | Transport Impact |\n|------|-------------|------------------|\n| `default` | Standard Apify tools | All tools available |\n| `apps` | OpenAI UI widgets mode | Additional UI widget resources |\n| `auto` | Capability-based detection | Mode resolved during initialize |\n\nSource: [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n\n## Request Handler Wiring\n\nAll transports delegate to the same core request handlers registered in `ActorsMcpServer`:\n\n```mermaid\ngraph TD\n T1[Stdio Transport] --> S[ActorsMcpServer]\n T2[HTTP Transport] --> S\n T3[WebSocket Transport] --> S\n\n S --> H1[ListToolsRequestHandler]\n S --> H2[CallToolRequestHandler]\n S --> H3[ListResourcesRequestHandler]\n S --> H4[ReadResourceRequestHandler]\n S --> H5[ListTasksRequestHandler]\n S --> H6[GetTaskRequestHandler]\n\n H1 --> T[Tool Execution]\n H2 --> T\n```\n\nSource: [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts) · [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n\n## Integration with MCP SDK\n\nThe transport layer uses the official `@modelcontextprotocol/sdk` package for protocol implementation:\n\n| SDK Component | Usage |\n|--------------|-------|\n| `Server` | Low-level MCP protocol server |\n| `StreamableHTTPServerTransport` | HTTP transport implementation |\n| `createStdioServer` | Stdio transport factory |\n| `RequestHandlerExtra` | Request context wrapper |\n\nSource: [src/stdio.ts](https://github.com/apify/apify-mcp-server/blob/main/src/stdio.ts) · [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)\n\n## Testing Transport Layers\n\nThe project includes transport-specific integration tests:\n\n| Test File | Transport | Coverage |\n|-----------|-----------|----------|\n| `tests/integration/suite.ts` | All transports | Main test suite |\n| `stdio.ts` (in integration) | Stdio | Stdin/stdout messaging |\n| `http.ts` (in integration) | HTTP Streamable | REST endpoints |\n| `sse.ts` (in integration) | Server-Sent Events | Notification streaming |\n\nSource: [DEVELOPMENT.md](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md) · [tests/integration/](https://github.com/apify/apify-mcp-server/blob/main/tests/integration/)\n\n## Summary\n\nThe Apify MCP Server implements a transport-agnostic architecture where:\n\n1. **Stdio Transport** handles local CLI clients through stdin/stdout JSON-RPC messaging\n2. **HTTP Transport** enables remote access via Streamable HTTP with session management\n3. **Core Server** (`ActorsMcpServer`) remains independent of transport implementation\n4. **Capability negotiation** occurs during MCP initialize handshake\n5. **All transports** delegate to the same request handlers for tools, resources, and tasks\n\nThis separation allows the server to serve both local development needs and production hosted deployments while maintaining a single, testable codebase.\n\n---\n\n\n\n## Tool System\n\n### Related Pages\n\nRelated topics: [Actor Tools](#actor-tools), [Storage Access Tools](#storage-tools)\n\n\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts) (primary server implementation)\n- [src/types.ts](https://github.com/apify/apify-mcp-server/blob/main/src/types.ts) (tool type definitions)\n- [src/tools/common/search_apify_docs.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/search_apify_docs.ts) (tool implementation example)\n- [src/mcp/proxy.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/proxy.ts) (Actor-MCP proxy tools)\n- [res/mcp_server_refactor_analysis.md](https://github.com/apify/apify-mcp-server/blob/main/res/mcp_server_refactor_analysis.md) (architecture analysis)\n- [res/mcp_resources_analysis.md](https://github.com/apify/apify-mcp-server/blob/main/res/mcp_resources_analysis.md) (resources and tools overview)\n\n\n# Tool System\n\nThe Tool System is the core component of the Apify MCP Server, enabling AI assistants to interact with Apify's platform capabilities through a standardized Model Context Protocol (MCP) interface. The system provides dynamic tool loading, registration, execution, and removal capabilities for three distinct tool types: internal helper tools, Actor tools, and Actor-MCP proxy tools.\n\n## Architecture Overview\n\nThe Tool System follows a centralized registration model where `ActorsMcpServer` manages all tool lifecycle operations. Tools are stored in a `Map` and exposed to MCP clients via request handlers. Source: [src/mcp/server.ts]()\n\n```mermaid\ngraph TD\n subgraph \"MCP Client\"\n A[Claude / VS Code]\n end\n \n subgraph \"ActorsMcpServer\"\n B[Server Instance]\n C[Tool Registry Map]\n D[setupToolHandlers]\n E[Central Dispatcher]\n end\n \n subgraph \"Tool Types\"\n F[HelperTool]\n G[ActorTool]\n H[ActorMcpTool]\n end\n \n A -->|tools/call| B\n B --> D\n D -->|route by type| E\n E -->|internal| F\n E -->|actor| G\n E -->|actor-mcp| H\n \n C -.->|stores| F\n C -.->|stores| G\n C -.->|stores| H\n```\n\n## Tool Type Definitions\n\nThe system defines three tool types through discriminated unions in `src/types.ts`. Source: [src/types.ts:135-174]()\n\n| Tool Type | Description | Execution Mode |\n|-----------|-------------|-----------------|\n| `HelperTool` | Internal server tools with direct callback execution | Synchronous |\n| `ActorTool` | Apify Actor-based tools for scalable execution | Asynchronous via Actor API |\n| `ActorMcpTool` | External MCP server tools proxied through Apify | Delegated to origin server |\n\n### HelperTool\n\nInternal tools that execute directly within the server process:\n\n```typescript\ntype HelperTool = ToolBase & {\n type: 'internal';\n call: (toolArgs: InternalToolArgs) => Promise