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.
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.
- 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.
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 thereposcope, which grants read and write access to every repository you can reach.
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.
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 aspostgresql://[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.
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
npxorpython. - Arguments: command-line arguments, passed in order.
- Environment variables: tokens or settings the server needs.
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].
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 themcpServers 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 inmcp.json in your Qualia config directory, next to settings.json:
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.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 afterstartup_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.
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.

