Connect AI agents to over 1000 apps to find documentation and execute authenticated API calls through a single interface.
Also known as withoneai/mcp, mcp, @withone/mcp
- Stars
- 12
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- 2.5.1
- Last commit
- Nov 13, 2026
- License
- MIT
What is One MCP?
One connects AI agents to over 1000 apps to find documentation and execute authenticated API calls through a single interface. It exposes 3 tools, such as list_one_integrations, find_one_actions, execute_one_action.
Summary generated from the project's README
About One MCP server
One provides a unified interface for AI agents to interact with over 1000 different applications. Instead of managing individual API keys or OAuth tokens for every service, developers can connect agents to platforms like Gmail, Slack, Shopify, and HubSpot through a single MCP server. This approach prevents tool bloat by exposing only three core tools to the agent, regardless of how many integrations are active, which helps keep the context window clean.
Users can deploy this as a local server using the One CLI and an API key from the dashboard, or as a remote server via a hosted HTTP endpoint. The system supports various clients including Claude Desktop, Cursor, Claude Code, and Windsurf. It includes fine-grained access control, allowing developers to restrict permissions to read, write, or admin levels and even require manual user approval before executing specific actions through MCP elicitation.
What you can do with it
- 1Execute cross-platform tasksAn agent can retrieve recent emails from Gmail or send messages to specific Slack channels using natural language.
- 2Manage platform integrationsThe server allows agents to discover available platforms and the specific actions they can perform through a single call.
Written from the project's README. Every use case is checked against a quote from it.
How to install One MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall One MCP in Claude Code
$ claude mcp add --env 'ONE_SECRET=<YOUR_ONE_SECRET>' mcp -- npx -y @withone/mcpInstall One MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@withone/mcp"
],
"env": {
"ONE_SECRET": "<YOUR_ONE_SECRET>"
}
}
}
}Install One MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@withone/mcp"
],
"env": {
"ONE_SECRET": "<YOUR_ONE_SECRET>"
}
}
}
}Install One MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp","type":"stdio","command":"npx","args":["-y","@withone/mcp"],"env":{"ONE_SECRET":"<YOUR_ONE_SECRET>"}}'Install One MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@withone/mcp"
],
"env": {
"ONE_SECRET": "<YOUR_ONE_SECRET>"
}
}
}
}Install One MCP in Codex
$ codex mcp add mcp --env 'ONE_SECRET=<YOUR_ONE_SECRET>' -- npx -y @withone/mcpInstall One MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp] command = "npx" args = ["-y", "@withone/mcp"] [mcp_servers.mcp.env] ONE_SECRET = "<YOUR_ONE_SECRET>"
Install One MCP in Gemini CLI
$ gemini mcp add -s user -e 'ONE_SECRET=<YOUR_ONE_SECRET>' mcp npx -- -y @withone/mcpInstall One MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp": {
"command": "npx",
"args": [
"-y",
"@withone/mcp"
],
"env": {
"ONE_SECRET": "<YOUR_ONE_SECRET>"
}
}
}
}Needs a key before it starts
Started on 16 Nov 2026 with no keys, it stopped and asked for one, so a client sees no tools until you set the variables above.
One MCP tools 3
Detected from the READMElist_one_integrationsfind_one_actionsexecute_one_action
Configuration
ONE_SECRETRequiredSecretOne API key from https://app.withone.ai/settings/api-keys
ONE_ACTION_IDSComma-separated action IDs the agent may see and run, or * for all
ONE_APPROVALAsk the user to approve actions before they run: off, delete (delete actions) or write (write and delete actions). Needs a client that supports MCP elicitation
ONE_CONNECTION_KEYSComma-separated connection keys the agent may see, or * for all
ONE_IDENTITYScope connections to a single user, team, organization or project identifier
ONE_IDENTITY_TYPEType of ONE_IDENTITY: user, team, organization or project
ONE_KNOWLEDGE_AGENTSet true to drop execute_one_action and run in knowledge-only mode
ONE_PERMISSIONSRestrict actions by what they do: read (read actions only), write (read and write actions) or admin (all, including delete)
Automated checks
Ran Nov 12, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubConnect your AI agents to 1000+ apps through a single MCP server. Find the actions a task needs with their documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
npm install -g @withone/cli
one init
That's it. The One CLI will prompt you for your API key (get one from the One dashboard) and configure the MCP server for your environment: Claude Desktop, Cursor, Claude Code, Windsurf, or any MCP-compatible agent.
Capabilities
- 1000+ platforms. Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and more.
- Natural language execution. "read my last gmail email", "send a message to #general on Slack"
- Code generation. "build a form to send emails using Gmail", "create a dashboard that lists my Linear projects"
- No tool bloat. Only 3 tools exposed regardless of how many platforms or actions you connect. One call finds every action a task needs, across platforms, with its documentation, so your agent's context window stays clean.
- Fine-grained access control. Restrict which actions, connections, and permission levels (read, write, admin) your agent has access to.
- Secure by default. All requests proxied through One, secrets automatically redacted, no platform API keys to manage.
Examples
Execute actions directly:
"Get my last 5 emails from Gmail"
"Send a Slack message to #general: 'Meeting in 10 minutes'"
"Get all products from my Shopify store"
Generate integration code:
"Create a React form component that sends emails using Gmail"
"Build a dashboard that displays Linear users and their assigned projects with filtering"
"Create a paginatable table that fetches and displays QuickBooks invoices with search and sort"
Tools
The server exposes three MCP tools:
| Tool | Description |
|---|---|
list_one_integrations |
List available platforms and active connections, each with the access it confers (full, access levels, or specific actions) |
find_one_actions |
Find the action for every operation a task needs, across platforms, with its documentation, in one call; load fetches more of a document or an alternative's |
execute_one_action |
Execute an API action on a connected platform |
Finding actions
find_one_actions takes one requests entry per operation, each a kebab-case platform and a short intent naming the operation alone ("send a message to a channel", not the message). A task describes the whole job in general terms, and an ai_model names the model asking; agents are asked to send both with every find, since the task helps tell similar actions apart. For each intent, One's decision model picks the action to use; the answer documents it, sets apart a substitute when the model was unsure, and lists a few alternatives. A platform no active platform has (clickup for click-up) is not searched: the answer names the platforms it may have meant, closest first, so the agent can ask again with the right one. Large documents come back as a digest; call find_one_actions again with load: [{ action_id, section }] for a section it left out, full: true for the whole document, or toc: true for its table of contents. ONE_ACTION_IDS, ONE_PERMISSIONS and ONE_CONNECTION_KEYS apply to every answer: an action they refuse is never offered, and when they refuse the model's pick, the next allowed candidate takes its place.
Upgrading from 1.x: search_one_platform_actions and get_one_action_knowledge are removed. find_one_actions replaces both.
Remote MCP Server
Prefer not to run anything locally? One hosts a remote MCP server at https://mcp.withone.ai/mcp. Point any MCP client that supports remote (HTTP) servers at that URL and authenticate with One via OAuth. There's no npm install and no ONE_SECRET to manage. You approve access in One's consent screen, where you can scope exactly which connections, actions, and permission levels the agent gets. Those choices are surfaced back to the agent through each connection's access field, so it knows what it can run without searching.
Add it to your client's MCP configuration. The endpoint speaks the Streamable HTTP transport:
{
"mcpServers": {
"one": {
"type": "http",
"url": "https://mcp.withone.ai/mcp"
}
}
}
Some clients omit type and take the URL alone; UI-based clients (custom connectors) just need the URL itself. On first connect, your client opens a browser to authenticate and authorize with One. After that, the same three tools are available.
One-click install:
The Windsurf link opens One's page in the editor's MCP marketplace, which is served from the official MCP registry where One is published as ai.withone/mcp. Windsurf handles the OAuth sign-in itself once you install from that page.
Manual Installation
If you prefer to configure the server manually instead of using one init, install the package directly:
npm install @withone/mcp
Then set the required environment variable:
ONE_SECRET=your-one-secret-key
Identity Scoping
Scope connections to a specific identity (e.g., a user, team, or organization):
ONE_IDENTITY=user_123
ONE_IDENTITY_TYPE=user
| Variable | Description | Values |
|---|---|---|
ONE_IDENTITY |
The identifier for the entity (e.g., user ID, team ID) | Any string |
ONE_IDENTITY_TYPE |
The type of identity | user, team, organization, project |
When set, the MCP server will only return connections associated with the specified identity, and execute_one_action will only run on those connections. This is useful for multi-tenant applications where you want to scope integrations to specific users or entities.
Access Control
Fine-tune what the MCP server can see and do:
ONE_PERMISSIONS=read
ONE_APPROVAL=write
ONE_CONNECTION_KEYS=conn_key_1,conn_key_2
ONE_ACTION_IDS=action_id_1,action_id_2
ONE_KNOWLEDGE_AGENT=true
| Variable | Type | Default | Description |
|---|---|---|---|
ONE_PERMISSIONS |
read | write | admin |
admin |
Filter actions by One's access classification of what each one does, whatever its HTTP method. read = read actions only, write = read and write actions, admin = all actions including delete. Below admin, an action with no classification is refused |
ONE_APPROVAL |
off | delete | write |
off |
Ask the user before an action runs. delete asks for delete actions, write asks for write and delete actions, and read actions never ask. An action with no classification is asked about at both levels. See Approval |
ONE_CONNECTION_KEYS |
* or comma-separated keys |
* |
Restrict visible connections and platforms to specific connection keys |
ONE_ACTION_IDS |
* or comma-separated IDs |
* |
Restrict visible and executable actions to specific action IDs |
ONE_KNOWLEDGE_AGENT |
true | false |
false |
Remove the execute_one_action tool entirely, forcing knowledge-only mode. find_one_actions then returns each chosen action's whole document with how to call it from code, and an Integration Code Guide (passthrough URL, x-one-* headers, ONE_SECRET / ONE_{PLATFORM}_CONNECTION_KEY env vars, backend-only placement) for writing application code |
All defaults preserve current behavior. If no access control env vars are set, the server starts with full access and all tools available.
Whatever you configure here is surfaced back to the agent: list_one_integrations stamps each connection with an access field so the agent knows up front what it can run there, without spending a turn searching. It is one of:
access |
When |
|---|---|
{ "policy": "full" } |
No action allowlist and ONE_PERMISSIONS=admin — every action is runnable. |
{ "policy": "levels", "levels": ["read", ...] } |
No action allowlist, but ONE_PERMISSIONS is read/write — only actions classified at these access levels are runnable. |
{ "policy": "actions", "actions": [{ "actionId", "title", "method" }] } |
ONE_ACTION_IDS is set — exactly these actions (the ones on that connection's platform) are runnable, so no search is needed. |
Approval
An agent that has just read an email, a web page or another third-party document can be steered by what it read. With ONE_APPROVAL set, the person at the MCP client decides whether a change goes ahead, not the agent.
Before execute_one_action runs an action that needs approval, the server shows a prompt through MCP elicitation. It names the action, the platform, the connection and what will be sent, and the user ticks a box to run it. Declining, dismissing, leaving the box unticked or not answering within 10 minutes stops the action, and nothing is sent.
Your MCP client has to support elicitation. If it doesn't, every action that needs approval is refused, so check your client before turning this on.
Manual Configuration
If you used one init, the configuration below is already done for you. These examples are for reference or manual setups.
Standalone
npx @withone/mcp
Requires Node.js 22.23.4+, 24.22.1+ or 26.12.1+. Older Node trusts the compromised eMudhra CA certificates (October 2026), so a network attacker could intercept ONE_SECRET. On an older Node the server still starts, but every tool returns an error with the command that updates Node for how it was installed. If you can't update yet, ONE_ALLOW_UNPATCHED_NODE=1 lets it call One anyway; you remain exposed while it is set.
Claude Desktop / Cursor
Add the following to your MCP config:
- Claude Desktop: MacOS:
~/Library/Application\ Support/Claude/claude_desktop_config.json· Windows:%APPDATA%/Claude/claude_desktop_config.json - Cursor: Open the Cursor menu and select "MCP Settings"
{
"mcpServers": {
"one": {
"command": "npx",
"args": ["@withone/mcp"],
"env": {
"ONE_SECRET": "your-one-secret-key"
}
}
}
}
Docker
docker build -t one-mcp-server .
docker run -e ONE_SECRET=your_one_secret_key one-mcp-server
All environment variables listed above can be passed as -e flags.
Security
All requests to third-party platforms are authenticated and proxied through One's API. The MCP server never handles OAuth tokens or platform API keys directly. The ONE_SECRET key is the sole credential required, and it is automatically redacted from all response payloads returned to clients. Sensitive headers are stripped from logged and returned request configurations.
License
MIT
Support
For support, please contact support@withone.ai or visit https://withone.ai
One MCP questions
How do I add One MCP to Claude Code?
Run claude mcp add --env 'ONE_SECRET=<YOUR_ONE_SECRET>' mcp -- npx -y @withone/mcp in your terminal. Add --scope user to make it available in every project.
How do I add One MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does One MCP provide?
It exposes 3 tools, including list_one_integrations, find_one_actions, execute_one_action.
How many platforms does One support?
One supports over 1000 platforms, including Gmail, Slack, Shopify, HubSpot, Stripe, Linear, and QuickBooks.
Do I need to manage individual API keys for every app?
No, you can execute API calls across platforms without having to manage OAuth tokens or API keys manually.
Can I restrict what my agent is allowed to do?
Yes, you can use fine-grained access control to restrict which actions, connections, and permission levels (read, write, admin) your agent can access.
How does the approval process work for sensitive actions?
When ONE_APPROVAL is enabled, the MCP client will prompt the user to approve an action before it runs, ensuring the person decides rather than the agent.