Apify Agent MCP

MCP server for custom automation tools using Apify Agent

> Part of Project Codify

Project Codify

- Login - reusable authentication sessions - TBD

- Agent - turn scripts into browser actions
- Coder - turn browser actions into scripts (TBD - currently integrated)
- Robot - automation engine for scalability (TBD - currently integrated)

More is on the way... Give it a shot 🎬 or join the list to follow the project! 🔔

What It Does

Model Context Protocol (MCP) server that lets AI assistants (e.g. Claude, Cursor, VS Code) execute browser automation tasks via Apify Agent. Tools are passed as clean JSON arguments — one per line. No manual setup or file creation.

Usage

Run directly using npx:

``bash
npx apify-agent-mcp {{MCP_TOOL_JSON}}
`

Or install locally:

`bash
npm install -g apify-agent-mcp
`

Quick Start

$3

Optional - you can also place the token inside the MCP server JSON later.

`bash
apify login
`

This saves your token to ~/.apify/auth.json.

Alternatively, set the environment variable:

`bash
export APIFY_TOKEN="your_token_here"
`

$3

Apify Coder can turn casual browser actions into reusable AI tools.
Currently, this feature is also integrated in Apify Agent

Export a tool and append the result as a JSON string to the MCP server args field or ask your AI to do it for you.

`json
{
"name": "scrape_product",
"description": "Scrape product info from a page",
"inputSchema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "Product page URL"
}
},
"required": ["url"]
},
"implementation": {
"type": "apify-actor",
"actorId": "cyberfly/apify-agent",
"script": "await page.goto(inputs.url); const title = await page.textContent('h1'); return {title};"
}
}
`

$3

`bash
npx apify-agent-mcp '{"name":"scrape_product","description":"...","inputSchema":{...},"implementation":{...}}'
`

Or with multiple tools:

`bash
npx apify-agent-mcp \
'{"name":"tool1",...}' \
'{"name":"tool2",...}' \
'{"name":"tool3",...}'
`

$3

Edit your Claude Desktop config:

macOS/Linux: ~/.config/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

`json
{
"mcpServers": {
"apify-agent": {
"command": "npx",
"args": [
"apify-agent-mcp",
"{\"name\":\"scrape_product\",\"description\":\"...\",\"inputSchema\":{...},\"implementation\":{...}}"
],
"env": {
"APIFY_TOKEN": "your_token_or_leave_empty_to_use_auth_file"
}
}
}
}
`

Restart Claude. Your tools are now available to the AI assistant.

Tool Definition Reference

$3

`javascript
{
// Required
"name": "tool_name", // alphanumeric + underscore/dash
"description": "What the tool does", // shown to AI
"inputSchema": {
"type": "object",
"properties": {
"paramName": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["paramName"]
},
"implementation": {
"type": "apify-actor",
"actorId": "cyberfly/apify-agent", // actor to run
"script": "await page.goto(inputs.url); ..." // Playwright code
},

// Optional
"version": "1.0.0",
"metadata": { "custom": "fields" }
}
`

$3

- script: Playwright automation code. Receives inputs object with user-provided parameters and page object for browser automation.
- actorId: Apify actor to execute. Defaults to cyberfly/apify-agent.

$3

Simple text input:
`json
{
"url": {
"type": "string",
"description": "Website URL"
}
}
`

Optional field:
`json
{
"timeout": {
"type": "integer",
"description": "Timeout in seconds",
"default": 30
}
}
`

Enum (dropdown):
`json
{
"format": {
"type": "string",
"enum": ["json", "csv", "markdown"],
"description": "Output format"
}
}
`

Usage Patterns

$3

`bash
npx apify-agent-mcp '{"name":"test","description":"Test tool","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"console.log('hello')"}}'
`

$3

`bash
npx apify-agent-mcp \
"$(cat tools/scraper.json)" \
"$(cat tools/logger.json)" \
"$(cat tools/analyzer.json)"
`

$3

`bash
APIFY_TOKEN="apk_..." npx apify-agent-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'
`

$3

`bash
cd /path/to/apify-agent-mcp
npm link

Now use anywhere


apify-agent-mcp '{"name":"...","description":"...","inputSchema":{},"implementation":{"type":"apify-actor","script":"..."}}'
`

Authentication

Token resolution order:

1. APIFY_TOKEN environment variable (if set and not empty)
2. ~/.apify/auth.json (from apify login CLI command)
3. Error: No token found, tool execution will fail with clear message

Troubleshooting

$3

Ensure you're passing valid JSON strings as arguments:

`bash


✓ Correct

npx apify-agent-mcp '{"name":"test","description":"Test","inputSchema":{"type":"object","properties":{}},"implementation":{"type":"apify-actor","script":"return {ok:true}"}}'

✗ Wrong (missing quotes around JSON)

npx apify-agent-mcp {name:"test"...}

✗ Wrong (single quotes around JSON on Linux/Mac may need escaping)

npx apify-agent-mcp '{name:"test"...}' # Use double quotes inside
`

$3

Ensure authentication is set up:

`bash


Option 1: Login via CLI

apify login

Option 2: Set environment variable

export APIFY_TOKEN="apk_your_token_here"
apify token
`

$3

Check your Playwright script syntax. The script must be valid JavaScript that:

- Has access to inputs (user-provided parameters)
- Has access to page (Playwright page object)
- Returns a value or object

`javascript
// ✓ Valid
await page.goto(inputs.url);
const title = await page.textContent('h1');
return { title };

// ✗ Invalid (missing await)
page.goto(inputs.url);
`

$3

If you have many tools, consider splitting into multiple MCP servers:

`json
{
"mcpServers": {
"apify-scraper": {
"command": "npx",
"args": ["apify-agent-mcp", "...tool1...", "...tool2..."]
},
"apify-analyzer": {
"command": "npx",
"args": ["apify-agent-mcp", "...tool3...", "...tool4..."]
}
}
}
`

Development

$3

`bash
npm link
apify-agent-mcp '{"name":"test",...}'
`

$3

`
lib/
index.js # Main entry: assembleWrapperCode(), start()
mcp/
resolver.js # Module path bootstrapping
auth.js # Token resolution
actor_caller.js # Apify actor execution
server_setup.js # MCP server + tool registration

bin/
start.js # Executable entry point (bin field in package.json)
``

Key Design Principles

- No files: Tools passed entirely via argv; no config files or manual setup.
- No base64: Clean, readable command lines; no obfuscation.
- Self-contained: All dependencies bundled; works offline once installed.
- Stateless: Each invocation is independent; easy horizontal scaling.
- Token from env/CLI: Seamless auth experience; respects Apify ecosystem conventions.

License

Apache-2.0

Contributing

Issues and PRs welcome at github.com/cybairfly/apify-agent