MCP

arg.ai exposes workspaces through a Model Context Protocol server over Streamable HTTP. Any MCP client can connect and work in the workspace directly - reading and writing files, running commands, searching, deploying servers and sites, and running Actions. Use MCP when the agent already exists somewhere else and you want it to reach your workspace. Use the Agent API when you want arg.ai to run the agent for you.

Endpoints

Scope	URL	Tools take `workspace_id`?
Root	`POST https://api.arg.ai/mcp`	Depends on the credential. OAuth picks the target during sign-in; an org-bound API key resolves to its organization.
Workspace	`POST https://api.arg.ai/mcp/{workspace_id}`	No. The connection is one workspace.
Organization	`POST https://api.arg.ai/mcp/org/{organization_id}`	Yes, on every workspace-bound tool. Adds `list_workspaces`.

Access is enforced per call: an organization-scoped connection only reaches the workspaces the credential can already access, and a read-only member cannot invoke a write tool.

Connecting

# OAuth (interactive)
claude mcp add -t http arg https://api.arg.ai/mcp

# API key, one workspace
claude mcp add -t http arg-workspace \
  https://api.arg.ai/mcp/{workspace_id} \
  -H "x-api-key: YOUR_API_KEY"

# API key, whole organization
claude mcp add -t http arg-org \
  https://api.arg.ai/mcp \
  -H "x-api-key: YOUR_API_KEY"

# OAuth
codex mcp add arg --url https://api.arg.ai/mcp
codex mcp login arg

# API key
export ARG_API_KEY=YOUR_API_KEY
codex mcp add arg-workspace \
  --url https://api.arg.ai/mcp/{workspace_id} \
  --bearer-token-env-var ARG_API_KEY

Both user-owned and service-account keys work. A user-owned key uses your access within the key’s organization; a service-account key uses that account’s role and grants - see API keys.

Tools

The MCP server exposes the agent’s own tools, plus a few that exist only over MCP for binary transfer and workspace discovery.

Files

Tool	Purpose
`read_file`	Read a UTF-8 file, with optional line offset and limit
`write_file`	Create or overwrite a text file
`edit_file`	Replace a string in a file
`multi_edit`	Apply several replacements in one write
`move_files`	Move or rename files
`list_files`	List a folder
`grep`	Regex search across files
`semantic_search`	Natural-language search over indexed content
`get_file_urls`	Get URLs for workspace files
`create_upload_session`	Upload a large or binary file, up to 5 GB, in parts
`download_file`	Download a file; binary comes back as an embedded resource

Shell and code

Tool	Purpose
`run_bash`	Run a shell command in the workspace sandbox
`run_code`	Write JavaScript that calls the other tools as functions

Actions

Four meta-tools front the whole Action catalog, so the client never carries a schema per Action.

Tool	Purpose
`search_actions`	Find Actions and their input schemas
`describe_action`	Drill into one Action, including fields whose options are dynamic
`run_action`	Run one by id with typed input
`list_runs`	List previous runs with status and output

Web

Tool	Purpose
`browse_url`	Fetch a URL as Markdown
`browse_web`	Drive a live browser session you can watch from the workspace
`screenshot_url`	Save a screenshot into the workspace
`extract_webpage_data`	Extract structured data from a page
`people_data_search`, `company_data_search`	Find people and companies by role, firmographics and tech stack
`people_data_enrich`, `company_data_enrich`	Fill in one person’s or company’s profile
`people_data_contact`	Find a work email or phone number, or verify an address
`company_data_signals`	A company’s open roles and recent news

Sites

Tool	Purpose
`deploy_site`, `get_site_deploy`, `list_sites`	Build and deploy a hosted site from a workspace folder
`promote_site_version`, `set_site_access`, `get_site_share_link`, `list_site_env`, `delete_site`	Manage a site once it exists

Automations

Tool	Purpose
`deploy_automation`	Register an automation file’s persistent triggers
`list_automation_deployments`, `list_automation_history`	Inspect what is deployed and what has run
`manage_automation_deployment`	Pause, resume, stop, or remove a deployment
`request_service_account`	Pick the service account an automation’s triggers run as, and grant it the files it needs

Skills, comments, and notifications

Tool	Purpose
`list_skills`	List bundled and workspace skills
`load_skill`	Load one skill’s full instructions by name
`comment_on_file`, `view_comments`	Read and post comments on a workspace file
`send_notification`	Notify yourself or same-organization teammates with an Arg file, folder, chat, or Action-run target

For send_notification, omit users or pass me to notify yourself. Recipients can also be user ids or email addresses. Omit channels for all delivery, or select any of ios, email, and in-app; recipient preferences still apply. A target derives the notification title, so title is optional when target is present.

Organization scope only

Tool	Purpose
`list_workspaces`	List the workspaces you can access. Call this first, then pass `workspace_id` to every other tool.

Tools carry MCP annotations, so a client can tell read-only tools from destructive ones before calling them.

Working well over MCP

Call list_skills before starting a task you have a skill for. Skills are how a workspace tells an agent your conventions; loading one is cheaper than inferring them.
Prefer create_upload_session over base64 in a tool argument for anything large. It returns a manifest with the file’s Arg URL plus the part, complete, and abort URLs. The completion response returns the file URL again after the upload finishes.
Use the URL returned by write_file to open the created file directly in Arg.
Reach for run_action before hand-rolling a capability - media generation, PDF rendering, and integration calls already exist in the catalog.

Agents overview - the same abilities, driven by the API instead
Tools - the REST equivalents of the file and shell tools
Actions - what search_actions is searching
API keys - credentials for non-OAuth clients

Getting started

Building with agents

Core concepts

Apps

Arg SDK

Integrations

Command line

Recipes & patterns

Changelog

Endpoints

Connecting

Tools

Files

Shell and code

Actions

Web

Sites

Automations

Skills, comments, and notifications

Organization scope only

Working well over MCP

​Endpoints

​Connecting

​Tools

​Files

​Shell and code

​Actions

​Web

​Sites

​Automations

​Skills, comments, and notifications

​Organization scope only

​Working well over MCP

​Related

Endpoints

Connecting

Tools

Files

Shell and code

Actions

Web

Sites

Automations

Skills, comments, and notifications

Organization scope only

Working well over MCP

Related