Skip to main content
Install a connector or add an MCP server so the agent can use outside tools during your chats. For example, connect Linear and the agent can read and file issues from what it finds. MCP (Model Context Protocol) is an open standard in which a server publishes tools and Qualia calls them. You decide which servers run and which tools need your approval. Manage everything in Customize agent > MCP Servers, which you open from the gear menu in the titlebar.
Only connect MCP servers you trust, because a server can read the data and chat content you send its tools.

Browse the connector catalog

Click Browse connectors to install a preconfigured connector. How you connect depends on the connector: In Qualia Cloud you can also add any MCP server that has a public URL. Your servers are visible only to you, and Qualia encrypts the headers you configure. Command-based servers, which run as local processes, work only in the desktop app.

Sign in to a connector

Linear, Atlassian, Sentry, Notion, and Stripe use browser sign-in.
1

Install the connector

In Browse connectors, choose the connector and install it.
2

Sign in

Select Sign in on the server and authorize access. Finish in the same browser where you started, because an authorization link opened elsewhere fails.
3

Return to Qualia

Choose Return to Qualia. Qualia loads the connector’s tools and returns you to the workspace where you started. If loading tools fails, choose Refresh tools.
In Qualia Cloud, to revoke a server’s authorization, select it and choose Unlink account. Deleting the server alone keeps the authorization in case you reinstall it. Changing a server’s URL or OAuth client may require signing in again.

Connect Google Drive and BigQuery

1

Choose the service

In Browse connectors, choose Google Drive or BigQuery. For BigQuery, enter the Execution and billing project first.
2

Authorize Google

Click Connect with Google, approve access, and select Return to Qualia.
Each service connects separately, and connecting the second asks for its additional permission.
  • BigQuery explores datasets and tables in your saved project and runs read-only queries. Your Google account needs permission to run jobs in that project and read the queried tables. Google bills the saved project.
  • Google Drive searches and reads Docs, Sheets, Slides, and other files you can access, including shared drives. Files with download restrictions stay restricted.
To see your Google account, reconnect, or disconnect, select the service in the MCP Servers list. To change BigQuery’s billing project, edit it and choose Reconnect with Google. Disconnecting one service keeps the other connected, so disconnect both before switching Google accounts. If you use the desktop app, connect Qualia Cloud in settings first, then sign in with the same Qualia account when your browser opens. Desktop and Cloud share one Google connection, so disconnecting in either affects both. If Google connections are unavailable, contact your Qualia administrator.

Connect OneDrive

In Browse connectors, choose OneDrive, then Connect with Microsoft. The connector is read-only and doesn’t need a Copilot license. The agent can search your OneDrive and read Word and text files. For example, ask it to summarize a document or compare two. It reads your own OneDrive only, not SharePoint libraries or sharing links. If a Word file is too large to read, split it or export it as text. If Microsoft connections are unavailable, contact your Qualia administrator.

Managed connectors

A managed connector is backed by a built-in Qualia integration instead of a server you configure. You sign in once in settings, and Qualia handles the credentials, so there is no token to paste into the server. Some managed connectors also appear in the MCP Servers list, where you can set their tool permissions. To change or remove one, choose Manage connection to open its settings. Connect and authorize each integration before you ask the agent to use it. For Databricks, also select a Genie Space. If you connect a service during an agent turn, send another message to use its tools.

Grant GitHub access

Connecting GitHub serves two purposes: it powers the GitHub connector, and it lets Qualia clone your private repositories. To clone, use Clone from GitHub in the File actions menu or on an empty workspace, or ask the agent. See Clone a repository. Public repositories need no connection. Set up access in Settings > Integrations > GitHub in one of two ways:
  • Connect the Qualia GitHub App (Qualia Cloud). Click Connect GitHub, then pick the account and repositories Qualia may read on GitHub. The App can only read contents, metadata, issues, and pull requests, so you can’t grant more by accident. To change repositories later, click Manage on GitHub.
  • Paste a fine-grained personal access token into Fine-grained personal access token. Use this on desktop, in organizations that block third-party GitHub Apps, or if you prefer a token. Qualia accepts only fine-grained tokens, which start with github_pat_. Classic tokens carry the repo scope, which grants read and write access to every repository you can reach.
A token is bound to one account or organization, so use the App if your repositories span several. If you set up both, Qualia uses the App. If a clone fails because the App doesn’t cover a repository, the clone dialog links to the GitHub page that fixes it.

What the token needs

One token serves both cloning and the GitHub connector, so scope it for whichever you use. Restrict it to the repositories Qualia should reach. On desktop, cloning uses the git credentials already on your machine, the same ones git clone uses in your terminal. The token still matters there for the GitHub connector.
Save your token in settings, not inside a repository URL, because a URL can expose it in your workspace files.

Connect Postgres

To let the agent query a PostgreSQL database from your notebooks, paste its connection URL into Settings > Integrations > Postgres. Use a URL such as postgresql://[USER]:[PASSWORD]@[HOST]:5432/[DATABASE]. Qualia masks the credentials once you save, and the agent never sees the URL in chat. To disconnect, click the trash icon next to the field.
  • Connect as a read-only database role so the agent can’t change your data, because the agent can write when you ask it to.
  • If you use Qualia Cloud, the database must accept public connections over TLS. Qualia Cloud can’t reach a database behind an IP allowlist or inside a private network. Connect from the desktop app instead.
In Qualia Cloud, each member saves their own connection URL.

Add a custom server

1

Open MCP Servers

Open a workspace, then open Customize agent > MCP Servers from the gear menu in the titlebar.
2

Start a new server

Click Add custom server.
3

Configure it

Enter a Server name, then fill in the fields below or paste a JSON configuration. Click Create.
4

Sign in if needed

If the server uses OAuth, click Sign in and complete the browser flow.

Command-based (stdio) servers

A command-based server runs as a local process, so it works only in the desktop app. Set:
  • Command: the executable to run, such as npx or python.
  • Arguments: command-line arguments, passed in order.
  • Environment variables: tokens or settings the server needs.
Put every token the server needs under Environment variables, because Qualia doesn’t pass through variables exported in your shell.

URL-based (HTTP/SSE) servers

A URL-based server runs elsewhere and works in Qualia Cloud and on desktop. Set:
  • URL: the server endpoint.
  • Headers: optional authentication headers, such as Authorization: Bearer [YOUR_TOKEN].
On desktop you can use any http or https URL, including a local server such as http://localhost:3000/mcp. Qualia Cloud needs a publicly reachable URL, and OAuth sign-in needs HTTPS.

Paste a JSON configuration

Switch Input mode to JSON and paste a configuration. Qualia accepts a single server’s settings, or the mcpServers format that Cursor’s mcp.json uses:

Manage tools

Select a server to see its tools. Each tool shows its name, description, and permission. Use the Enabled switch to turn a whole server on or off. If a server can’t connect, its error appears at the top of its detail view.

Set tool permissions

Most new tools default to Ask each time. When the agent wants one of those tools, an approval request appears above the message box. Choose Run to approve this use, or Skip to decline and let the agent continue without it. To approve future uses too, pick an Always allow option from the request’s dropdown.

View a tool’s schema

Click Show schema on a tool to see the parameters it accepts and their types.

Refresh tools

If a server’s tools change, such as after an update, click Refresh tools to rediscover them.

Edit the configuration file

In the desktop app, Qualia stores MCP servers in mcp.json in your Qualia config directory, next to settings.json:
Valid tool_permissions values are always, ask, and never. Qualia picks up edits to the file automatically.

Timeouts

Two optional per-server fields, in seconds, bound how long Qualia waits. Set them only if a server legitimately needs longer.
Raise startup_timeout_seconds for a server that is slow to boot. For example, a server started with npx -y is slowest on its first run, while the package downloads. Raise tool_call_timeout_seconds for tools that do long-running work.

Troubleshooting

Server won’t connect

The server’s detail view shows the error. Check that the command or URL is correct, that the server’s dependencies are installed, and that any credentials it needs are set.

Server doesn’t respond

If a server accepts the connection but never answers, Qualia stops waiting after startup_timeout_seconds and shows the error in chat. Common causes are a wrong command or URL, a missing dependency or credential, or a command waiting for input. If the server is slow to start, raise startup_timeout_seconds.

Server needs signing in again

OAuth tokens eventually expire. When Qualia can’t renew one, the server shows a Sign in button, and its tools stop working until you sign in again. If this happens during a chat, a sign-in card appears in the conversation. Use the card to sign in, and the agent continues with other work meanwhile. If the sign-in window doesn’t close after you authorize, close it yourself. On desktop, signing in to a local MCP server opens your default browser and a sign-in dialog in Qualia. If sign-in doesn’t finish on its own, such as over SSH, paste the full callback URL from the browser’s address bar into the dialog. Qualia rejects expired or mismatched callback URLs, so start again if that happens.

Server needs an OAuth client

Most OAuth servers let Qualia register itself on first sign-in, so there is nothing to configure. A few don’t, such as custom GitHub OAuth setups, Slack’s remote server, and Microsoft Entra. Those fail before a browser opens, with a message that the server needs an OAuth client. To connect one, register an OAuth app with that provider. Then select the server, click Edit, expand OAuth client, and fill in:
  • Client ID: from the app you registered. Required.
  • Client secret: only if the provider issued one. Leave it empty for a public client, which uses PKCE instead.
  • Redirect URI (desktop): a loopback address with a port that the app is registered with, such as http://localhost:8400/callback. Leave it empty if the provider accepts any loopback port, and Qualia picks a free one.
In Qualia Cloud, leave Redirect URI empty. Register https://[API_HOST]/api/mcp/oauth/callback with the provider instead, where [API_HOST] is your deployment’s API hostname. Sign in again after you change the client ID.
  • GitHub OAuth apps need a client secret. Register the same loopback redirect URI you enter in Qualia, then click Sign in.
  • Slack also requires the app to be published to the Slack directory or internal to your workspace, and a workspace admin must approve MCP servers.