29 Actions and tools
Actions let agents do more than read indexed documents. An action calls an external system on the user’s behalf, then returns the result into the conversation. Use actions when an agent needs live data, needs to look something up by ID, or needs to trigger a workflow you already run elsewhere.
This chapter covers the two action surfaces workspace admins manage:
- MCP Actions on the Connectors page (
/app/connectors), in the Personal or Shared tab depending on who can use the server. Register a Model Context Protocol server, configure how Nous authenticates to it, and pull its catalog of tools. - OpenAPI Actions on the Shared tab of the same page. Paste an OpenAPI spec, choose how each request is authenticated, and expose individual endpoints as tools.
The default assistant derives its MCP actions at request time from the current user’s access. OpenAPI actions reach it only after a workspace admin turns them on in Chat Preferences. See Turn an action on for the default assistant.
29.1 Use apps and actions in chat
In the chat composer, + > Connectors is where a user chooses which apps Sophea can act with in a chat. Knowledge Search and the built-in actions have no switches: they are always on in chat. For the default assistant, the MCP apps a user can access appear there automatically. The Personal tab lists the apps the user signs in to with their own account, and the Shared tab lists the apps shared by the workspace, those that need no sign-in or that an admin signed in for everyone, together with standalone custom actions. Switching an MCP app on there creates an optional allowlist of that app’s enabled actions for the current chat. It is not a second access setting or a request that guarantees an action will run.
The composer toolbar has two controls that matter for this chapter:
- Add (plus icon) (Add to message) opens Upload files, Add from project files (files from all of the user’s projects, grouped by project), Saved prompts (also available by typing
/), Deep Research, and Connectors. It has no rows for Knowledge Search or the built-in actions, because those are always on. A small dot on the + button shows that a personal connector needs to be signed in again. - Agents opens the other published agents. See Agents.
Connectors opens the panel described below. It has a search box and the Personal and Shared tabs, each with a count of the apps that are on, such as 2/5. A tab shows a dot when one of its apps needs attention. Within a tab, apps that need attention come first, then the apps that are on.

- The built-in actions have no switches: they are always on in chat. On the default assistant these are Web Search, Open URL, Code Interpreter, Image Generation, and File Reader. When the current user has connected an app that is searched live, such as Microsoft Teams, Outlook, Gmail, IMAP mail, or Sophea Meet, Live App Search is also available. The Chart and Presentation agents are always on as well, and the model uses them for clear chart or deck requests. Admins still control which tools exist: a tool that the workspace turns off under Actions & Tools in Chat Preferences is not available in chat. Knowledge Search is always on over all sources the user and agent can access, with no scope to pick; a project chat answers from the project’s files.
- Each accessible MCP app, such as Zapier, appears automatically when the server is connected and your access scope permits it. Apps that each user signs in to with their own account are on the Personal tab, including apps the user has not connected yet. Apps that need no sign-in or that an admin signed in for everyone, and standalone custom actions such as OpenAPI actions, are on the Shared tab. If an app still needs a personal connection, its row reads Not connected yet, and turning its switch on opens the connection dialog instead of enabling the app. If a personal app was connected but needs to be signed in again, its row shows Reconnect instead of the switch, and the + button shows a dot. A shared app with a server problem shows its status only, because an admin fixes it. There is no separate per-user enable step in Chat Preferences.
- Switching an MCP app on makes that app’s enabled actions available throughout the current chat. You can keep up to two apps on in a chat; while two are on, the other app switches are unavailable and the panel says so. The model decides whether an action is useful and which allowed action to call; switching the app on does not guarantee execution. The app stays on after completed responses, technical failures, and cancelled responses. Turn it off in the Connectors panel when later messages no longer need it. Starting a New Chat or switching chats, assistants, or projects clears the selection.
- Refreshing the page clears MCP selections. It does not cancel an answer that is still being written: that answer keeps running and continues in the reopened chat. See Deep Research.
- The built-in actions are not chat selections. The model chooses an action only when it is useful, and being on does not force a call. If a user’s earlier saved preference for an agent turned a built-in action off, the composer turns it back on before the next message is sent.
- Choose the gear icon on an MCP app’s row to open its tool settings. The dialog lists the tools the app offers, each with its own switch. When an app offers tools from several providers, as Zapier does, the dialog groups them under one heading per provider, such as Gmail or Slack; an app with a single set of tools shows one list. The dialog also shows a count such as “3 of 5 tools on”, and offers Refresh when the app supports it. For a shared app, the switches choose which of the tools your admin enabled Sophea may use for you. These switches control whether an action may run, independently of the app’s chat-scoped switch. The built-in actions have no gear and no switch.
- Manage connectors at the bottom of the panel opens the Connectors page. All connectors in a connector’s settings dialog lists everything the user can use, with its state (On in this chat, Off, or Not connected) and Reconnect and Settings actions. Admins add MCP servers from Add connector > MCP servers on the Connectors page.
- Standalone OpenAPI actions use their own switches on the Shared tab, because they do not belong to an MCP app.
Live App Search reads directly from the current user’s personal connections. Use it for freshness questions such as meetings from today or recent mail from a sender, and for searches by meeting name, mail subject, sender, or body text. Gmail, Microsoft Outlook, and IMAP messages are never indexed in Knowledge Search. Nous never sends another member’s personal credentials, and disconnecting the last supported personal app removes its live capability.
Zapier’s provider actions are grouped by provider. Choose the gear icon on the Zapier row to see the enabled actions as individual switches under a heading for each provider, such as Gmail and Slack, with actions such as Find Email, Create Draft, and Send Email under Gmail. Then switch the Zapier app on to make those enabled actions available in the current chat. The model may call a relevant allowed action or answer without Zapier. Every newly discovered Zapier action starts off. An individual Find Email switch does not enable Send Email, another Gmail action, or another provider. The server’s settings on the Connectors page group the same actions by provider.

Choose Refresh in the tool settings after changing the enabled actions in Zapier. The control stays available even when the current catalog contains zero actions. It stays busy and blocks duplicate clicks until the complete refresh finishes. Nous replaces the current user’s catalog without changing another user’s catalog. If Zapier’s management contract is incompatible, Nous hides those actions instead of falling back to its generic management tools. A temporary connection failure or a catalog change during refresh keeps the last validated catalog and offers a retry.
Published external agents are composer controls in Agents rather than app gates, except Deep Research, which has its own control in the composer’s + menu. Knowledge Search has no control: it is always on over all sources the user and agent can access, and the model searches only when useful. Narrowing it to some sources under Connectors takes one of the four agent slots. MCP apps remain on in the current chat until the user turns them off. A published external agent, Deep Research included, stays selected for later messages in the chat, including when its run continues in the background, until the user turns it off. A published external agent can coexist with an MCP app selection, but the MCP allowlist applies only to Nous and is not sent to the remote agent. Knowledge Search can coexist with an MCP app selection: a message can search the knowledge base and then use an allowed action, and the reply covers both. Starting a New Chat or switching chats, assistants, or projects clears other chat-scoped selections while keeping the saved app configuration.
Deep Research searches only the workspace documents the person can read and the web. It does not use enabled apps, and it does not change saved app switches. If an allowed app or action is unavailable or does not fit the selected model, Nous removes it from the available tool set and can continue with the remaining valid work. Selecting an MCP app does not turn that warning, or a response that uses no MCP action, into a required-operation failure.
The composer permits at most four agents in one message. Separately, up to two apps (MCP connectors) can be on in a chat.
An MCP app being visible, ready, and selected are separate states. Visible means the server is connected and its access scope permits the user. Ready means any required personal authentication is complete. Selected means the user has made that app’s enabled actions available for the current chat; the model can still answer without calling one. Removing access, disconnecting the server, revoking personal credentials, or leaving the app with no enabled actions removes an existing selection before a later message.
29.1.1 Connect personal MCP credentials
An MCP server can be available to the workspace while still requiring each user to connect a personal account. The app row reports these states separately. A connected server that still needs your credentials reads Not connected yet; its switch starts the connection instead of turning the app on, and its tool settings stay unavailable until your connection succeeds.

- For an API-token connection, turn the app’s switch on, enter every requested credential, and submit the form. Nous tests the credentials against the live MCP server before saving them. A failed test leaves the previous connection unchanged.
- For OAuth, turn the app’s switch on and complete the provider’s authorization page. Nous returns you to the same chat after it verifies the new connection.
- Until your personal connection is complete, Nous excludes the app’s actions from the tools sent to the model. A stale selection cannot make Nous use the workspace creator’s credential.
- For a supported Zapier connection, a successful connection also discovers that user’s enabled provider actions. Use Refresh in the app’s tool settings when the enabled set changes in Zapier.

29.2 What actions are
An action is a named callable that an agent can invoke during a chat. Each call is a single, scoped request: the agent picks the action, fills in the arguments from the conversation, the request runs against your configured endpoint, and the response is fed back into the model so it can write a grounded answer.
Two action types are available:
- MCP tools. You register one MCP server. Nous discovers the tools it exposes, and each tool becomes an action you can turn on.
- OpenAPI tools. You upload one OpenAPI document. Each operation in the spec becomes an action you can turn on.
A third capability, Code Interpreter, is not on these pages. It is a switch under Actions & Tools in Chat Preferences that lets the default assistant run sandboxed Python during a chat. Manage it there, not here.
If a vendor offers both an MCP host and an OpenAPI spec, prefer MCP for richer tool descriptions and built-in argument schemas. Use OpenAPI when you only have a spec and no MCP wrapper.
Nous checks each call before sending it: the argument names, their types and the required arguments must match the action’s schema. The service behind the action checks everything else in the schema, such as allowed values, formats, ranges and patterns, and its error goes back to the assistant so it can correct the call. Nous does not resolve references to other schema documents; the service validates those parts of the call. For OpenAPI actions, a path parameter value must be a single path segment: Nous refuses values that contain /, \ or %.
29.2.1 Zapier provider actions and controller tools
Zapier’s MCP server publishes a small catalog of controller tools while managing a larger set of enabled actions for services such as Gmail, HubSpot, and ClickUp. A supported personal Zapier connection translates those enabled provider actions into individually selectable Nous actions.
This distinction affects both administration and chat:
- For an Individual Key (Per User) Zapier connection, the server’s settings on the Connectors page show provider groups and their individual actions, and the app’s tool settings in the composer list the same actions with individual switches. Zapier’s controller tools stay hidden and are not sent to the model as alternative actions.
- Every user connects their own Zapier credentials and receives an independent catalog. Newly discovered actions start off until that user enables them.
- A Shared Key (Admin) connection remains a standard MCP connection and uses the protocol tools published by its server. Nous does not automatically convert a shared connection or its catalog into a personal provider-action connection.
- A follow-up question can use results already present in the conversation. Select Zapier again only when the follow-up should make another live Zapier action available.
If an expected provider action is missing, enable it in Zapier and choose Refresh in the app’s tool settings. A zero-action catalog still offers Refresh. After changing an existing server from a shared key to an individual key, any user without a ready personal connection must switch the app on in Connectors and supply personal credentials before Nous can discover or execute that user’s provider actions.
29.2.2 Creating multiple ClickUp tasks through MCP
This is separate from the personal ClickUp Connector, which still uses exact-proposal confirmation and does not support bulk actions. For the verified ClickUp task-create action in the connected personal Zapier app, an already-authorized request for up to 16 independent tasks in the same resolved List and with supported fields is validated as a whole before any task is created. Nous then creates each task sequentially, without a second confirmation because the MCP action is already authorized. This limited capability does not extend to other providers or actions, mixed requests, or unresolved destinations. The response shows links for tasks that Nous verified as created and distinguishes tasks that have not been sent. See ClickUp task creation with an MCP action for same-member continuation and Stop or uncertain results.
29.3 MCP Actions
The Model Context Protocol is a standard for exposing a catalog of tools over HTTP. An MCP server publishes a list of tools, their input schemas, and their human-readable descriptions. Nous fetches that catalog, persists it, and lets you turn individual tools on.
Open Connectors (/app/connectors). For workspace admins with the Agents product enabled, MCP servers and OpenAPI actions are listed as rows after each tab’s connectors, in the same way as connectors:
- Personal shows your private MCP servers.
- Shared shows MCP servers shared with teams or the whole workspace, and every OpenAPI action, since OpenAPI actions are always workspace-wide.
- All shows everything, including other admins’ private servers, labelled with who owns them.
The page’s search box and the tab counts include MCP servers and OpenAPI actions.
Each row shows:
- The action’s name, with its description below it (or the server URL when an MCP server has no description).
- A label for the type, MCP or OpenAPI, and a label for who can use it: Private, Team, or Workspace. OpenAPI actions are always Workspace. Another admin’s private server reads Private to followed by that admin’s name.
- Its status: Connected, Needs sign-in, Fetching tools, or Disconnected.
- A count. An MCP server shows how many of its tools are on, such as “3 of 5 tools on”. An OpenAPI action shows how many tools its schema defines, such as “2 tools”.

Shared MCP servers and OpenAPI actions can also be managed in Portal: the workspace’s Connectors page in Portal has MCP and OpenAPI tabs, and Open in Portal in the notice above them on the Shared tab opens Portal’s MCP tab. Portal sets up servers with no authentication or an admin API token; servers that use OAuth or per-user sign-in, and OAuth on OpenAPI actions, are set up here.
29.3.1 Open an action’s settings
The gear at the end of a row, named Settings for followed by the action’s name, is the row’s only control. It opens a dialog named after the action that holds everything you can do with it:
- Connection. Shows the status and the control that fits it. Authenticate signs in to an action that still needs sign-in; an MCP app that each user signs in to with their own account shows Connect instead. Reconnect brings back an action that was disconnected. Disconnect turns a connected action off.
- Tools. Lists the action’s tools. See Discover and review tools for an MCP server; an OpenAPI action lists its endpoints read-only.
- Edit settings. Opens the same form you used to create the action, to change its connection details, access, or saved credentials.
- Delete. Appears only for an action that never finished sign-in. To remove a connected action, use Disconnect.
When you choose Disconnect, a confirmation opens with the title Disconnect and the action’s name. Select the checkbox Also delete followed by the action’s name to remove it completely, then choose Disconnect and delete. Without the checkbox, the action stays listed as Disconnected and Reconnect brings it back. See Remove an MCP server and Remove an OpenAPI action.
Once an MCP server is connected, its settings list its tools under Tools with a count such as “3 of 5 tools on”. When an MCP catalog supplies provider metadata, the dialog groups tools under providers; tools without provider metadata remain in one flat list. A supported Zapier server therefore shows groups such as Gmail, ClickUp, and Microsoft Outlook, while its internal management tools stay hidden. Every provider group starts collapsed. Select a provider to open it; a search temporarily opens matching groups, and clearing the search restores your previous choices.
- The Enable or disable all tools switch for the server turns its entire current tool list off in one operation, or on again.
- Each tool also has its own switch, named after the tool.
- Search tools narrows the list, and Show only enabled tools hides the tools that are off.
These switches control whether a tool is available to run; the app and action switches in chat separately control whether the selected assistant may choose it. For a personal Zapier connection, these controls affect only the current user’s discovered actions.

29.3.2 Register a new MCP server
Choose Add connector on the Connectors page, then the MCP servers tab. The tab shows the connection and access fields.

Fill in the fields:
- Server Name. A short label your admins will recognise. This is the name admins and users see for the action.
- Description (Optional). A sentence explaining what the host does. Other admins will see this when they pick which tools to attach.
- MCP Server URL. The endpoint of the MCP host. Use
https://for anything that leaves your network. Only connect to servers you trust. - Who can use this MCP server? Choose Private, Teams, or Workspace. Private is the default. Teams requires at least one active Portal Team; Workspace makes the app available to every active member of this workspace.
You can change the access scope later from the server’s Edit settings. Access controls whether a user can see, connect to, and execute the MCP app. It does not grant membership in the upstream service. Connections created before access scopes were introduced remain available to the Workspace for compatibility; review those connections and narrow their scope where appropriate.
Click Add Server. The dialog closes, the tab the server belongs to opens (Personal for a private server, Shared otherwise), and the server’s authentication step opens next. Nous fetches the tool catalog once authentication is configured.
29.3.3 Authentication modes
Choose the gear on the server’s row, then Authenticate in its settings (Connect for an app that each user signs in to with their own account). To review or change the saved credentials of a server that is already connected, choose Edit settings, then Edit Configs. The authentication modal exposes four modes:
- None. No credentials are sent. Use only for fully public, read-only MCP hosts you trust.
- OAuth. Users connect to the MCP host with OAuth. Optionally enter a
Client IDandClient Secretwhen the host does not support Dynamic Client Registration (DCR). A client ID may be saved without a secret. Choosing Clear for only the Client Secret while keeping the Client ID leaves OAuth configured with that ID. Choosing Clear for both returns the next connection to DCR. Nous rejects a secret without an ID, or choosing Clear for Client ID while keeping the secret. The modal shows the redirect URI to register with the host. - OAuth Pass-through. Nous forwards the user’s existing access token to the MCP host as an
Authorizationheader. Use this only when the host trusts the same identity provider as Nous. - API Key. Pick
Individual Key (Per User)so each user supplies their own key, orShared Key (Admin)to enter one organisation-wide key. The shared key is sent on every request as a bearer token.
Saved credentials appear as masks. The mask is display-only; do not copy it as a credential. For each field, choose Keep to retain the saved value, Replace to enter a new exact value, or Clear to remove it. If you choose Replace, even text that matches the displayed mask is saved as the new credential.
The API token for Shared Key (Admin) and every required credential field for Individual Key (Per User) must remain set. Clear is rejected for a required value, and the saved configuration stays unchanged.

Pick the mode the host supports. Mixing modes does not work: the server accepts OAuth, the pass-through token, the configured API key, or nothing.
29.3.4 Discover and review tools
After the server is saved, choose the gear on its row to see the discovered tools under Tools. While Nous is still fetching them, the row’s status reads Fetching tools. Each tool has a name (used by the model when calling it), a description (used by the model when deciding whether to call it), and an input schema (the arguments the tool accepts).
Nous derives the default assistant’s MCP actions at request time from the current user’s access. They appear as one available MCP app in the composer’s Connectors panel (+ > Connectors) only for users allowed by the server’s access scope: on the Personal tab when each user connects with their own credentials, and on the Shared tab for an app that needs no sign-in or that an admin signed in for everyone. The app remains off until the user chooses to make its enabled actions available for the current chat.
Review every tool before you allow agents to use it. The descriptions the model reads come directly from what the MCP server publishes. If a description is vague, the model will call the tool at the wrong moments. Edit the description on the host side and then refresh.
To refresh the catalog after the host adds or changes tools, click Refresh tools in the server’s settings. A supported action catalog uses Refresh actions instead. The refresh control stays busy until discovery and synchronization finish, then Nous shows the updated list without a page reload.
29.3.5 Remove an MCP server
Choose the gear on the server’s row, then Disconnect. Select the checkbox Also delete followed by the server’s name to remove the server and its settings as well, then choose Disconnect and delete. A server that never finished sign-in has no connection to disconnect, so its settings offer Delete directly. Its tools stop being available in chat immediately, whether you disconnect or delete. The action call disappears from the assistant’s tool list on the next chat. If you only disconnect, the server stays listed as Disconnected and Reconnect in its settings brings it back.
29.4 OpenAPI Actions
An OpenAPI action wraps a standard OpenAPI (Swagger) document. Nous parses the spec and turns each operation into a tool the assistant can call. The agent fills in the path, query, and body arguments from the conversation, then Nous sends the request with the auth configuration you set.
OpenAPI actions are listed as rows on the Shared and All tabs of the Connectors page, next to the MCP servers (see MCP Actions). After Add Action, the Shared tab opens with the action’s authentication step.
Choose a row’s gear to open the action’s settings (see Open an action’s settings). They show its status and a Name field, then its endpoints. The endpoints are read-only, each with its method and path, and Search endpoints narrows the list. An OpenAPI action is on or off as a whole: there are no switches for individual endpoints. To rename an action, change the Name field and choose Save. Edit settings opens the form you used to create it.
29.4.1 Register a new OpenAPI action
Choose Add connector on the Connectors page, then the OpenAPI actions tab. The tab shows a single input area.

The modal has one field:
- OpenAPI Schema Definition. Paste a JSON OpenAPI 3.x document. Nous validates it as you type. The action name, description, and base URL are read from the spec:
info.titlebecomes the action name,info.descriptionbecomes the description, and the first entry inservers[].urlbecomes the base URL Nous calls. There is no separate name or URL field. Edit your spec soinfo.titleis descriptive before pasting.
Once the schema validates, the preview area below the textarea shows each detected operation as a tool. If the schema is invalid or empty, the preview shows No Actions Found. Click Add Action. Each operation in the spec is then attachable as an individual tool. The entry is created without any authentication. Then open the action’s settings and choose Authenticate to configure authentication.
29.4.2 Authentication modes
Choose the gear on the action’s row, then Authenticate in its settings. To change how a connected action authenticates later, choose Edit settings, then Edit Configs. The authentication modal exposes three modes:
- OAuth. Nous performs an OAuth flow per user. Provide the
authorization URL,token URL,client ID,client secret, and any required scopes. Use this when the upstream API supports OAuth and you want per-user access tokens without the user managing the secret themselves. - Custom Authorization Header. Enter a fixed set of headers (typically
Authorization: Bearer …or a vendor-specific header) and Nous adds them to every call. Use this for service-to-service APIs that issue one long-lived key. - OAuth Pass-through. Nous forwards the end user’s existing access token to the upstream API. Use this when the API has its own per-user identity model under the same identity provider and you do not want Nous to hold a shared key.
Pick the mode that matches how the API expects to be called. Mixing modes inside one OpenAPI action is not supported. If you need two auth styles for the same vendor, register two separate OpenAPI actions.
29.4.3 Remove an OpenAPI action
Choose the gear on the action’s row, then Disconnect. Select the checkbox Also delete followed by the action’s name to remove it completely, then choose Disconnect and delete. An action that never finished sign-in offers Delete directly. Without the checkbox, the action stays listed as Disconnected and Reconnect brings it back. As with MCP servers, its operations stop being available on the next chat. Nothing else about the assistant’s configuration changes; only the tool call is removed.
29.5 Turn an action on for the default assistant
At request time, the default assistant receives the MCP actions accessible to the current user. OpenAPI actions are different: a workspace admin turns each one on for the default assistant in Chat Preferences.
To turn on a registered OpenAPI action:
- Open Settings > Chat Preferences.
- Expand Actions & Tools. Registered OpenAPI actions are listed below the built-in tools.
- Switch on the actions you want the default assistant to use.
- If the model needs guidance on when to use an action, add it to the System Prompt on the same page. A clear instruction beats a clever description.
The next time a user starts a chat, the tools are available to the model. The model decides when to call them; you cannot force a call from the page.
After switching an action on, validate it. Open a new chat, ask a concrete question that should trigger the tool, and confirm the assistant calls it with the right arguments. If the model never calls the tool, the description or the system prompt is the first place to fix.