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

An OAuth connection opens a browser, where you sign in and then allow the client to use your account before it receives a credential. arg.ai asks every time, because a client’s name is reported by the client itself.

# 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
`open_file`	Show an Arg file in the conversation, from a link someone shared or a path: also answers its workspace and path for the other tools, whether you may edit it, and its Arg URL
`read_file`	Read a UTF-8 file, with an optional 1-based line offset and line 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.

Arg files in the conversation

In ChatGPT and Claude, open_file also shows the file in the conversation as an interactive view - the same live viewer Arg uses, so a deck pages, a whiteboard pans and a spreadsheet scrolls. Anyone who can edit the file in Arg can edit it there too, as themselves, in the same live session as everyone who has it open in Arg; anyone who can only read it watches the changes arrive. Open in Arg opens the file in the app, Expand takes the view full screen, and Share copies the file’s Arg link or, if you can share the file, creates a public link that anyone can view for 7 days. In Claude, apps you built in Arg (.html, .tsx) and hosted sites don’t show inside the view; use Open in Arg for those. The view never holds your Arg sign-in. It asks the Arg server for a one-time link to the file each time it opens, checked against your access at that moment, so a file someone stops sharing with you stops opening. Paste an Arg link into the conversation and ask about it, and the assistant opens it with open_file before it reads or changes the file. The assistant also shows you what it makes. When it writes a document, board, design, deck or spreadsheet, the file appears in the conversation as soon as it is saved, and after it edits one it opens the result with open_file. Code and data files it writes stay out of the way.

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

Arg files in the conversation

Working well over MCP

​Endpoints

​Connecting

​Tools

​Files

​Shell and code

​Actions

​Web

​Sites

​Automations

​Skills, comments, and notifications

​Organization scope only

​Arg files in the conversation

​Working well over MCP

​Related

Endpoints

Connecting

Tools

Files

Shell and code

Actions

Web

Sites

Automations

Skills, comments, and notifications

Organization scope only

Arg files in the conversation

Working well over MCP

Related