---
title: Agent Connections
description: >-
  Connect Agents to Clear Ideas Sites and approved external MCP servers with
  controlled authentication, health checks, aliases, and evidence-aware source
  metadata.
ogTitle: Agent Connections
ogDescription: >-
  Learn how Agent Connections provide governed source and tool access for Clear
  Ideas Agents.
ogImage: /assets/images/og/agents-connections.webp
navigation:
  icon: fasl fa-plug-circle-bolt
---

# Agent Connections

Agent Connections are saved, governed connections that Agents can use to read from sources, call MCP tools, and optionally write back to approved systems. They make source access explicit: each connection has a provider, authentication method, tool alias, read/write mode, approved tools, health status, and evidence settings.

Use Agent Connections when an Agent needs access beyond the prompt itself, such as Clear Ideas Sites, an approved MCP provider, or a custom MCP server.

## Connection Types

Clear Ideas supports two setup patterns:

- **Predefined providers** are connection templates already known to Clear Ideas. They include provider metadata, default MCP settings, default instructions, and expected authentication details. Select the provider, supply any required credentials, test the connection, approve tools, then save.
- **Custom MCP Server** is for an MCP-compatible source managed outside the supported catalog. You provide the MCP URL, choose an authentication method, test the server, approve discovered tools, then save.

Predefined Agents and custom Agents use the same saved connections. A predefined Agent may suggest a source pattern, but the saved connection still controls authentication, allowed tools, mode, health, and evidence. A custom Agent can use built-in Clear Ideas access, predefined provider connections, custom MCP connections, or no sources at all.

## Add a Connection

Open **Agents** and go to **Agent Connections**, then choose **Add Connection**.

1. Pick a connection type from the provider list.
2. Fill in **Configuration** fields such as connection name, tool alias, MCP URL, and authentication.
3. Review or update **Skill instruction** so the Agent knows when and how to use the source.
4. Use **Test** or **Connect & test** to validate authentication and discover MCP tools.
5. Approve only the tools the Agent should be allowed to use.
6. Save the connection.

After the connection is saved, open an Agent in the builder and add it under the Agent's source settings. Steps can inherit the Agent's sources, use a narrower source policy, or run with no sources.

## Configuration Fields

| Field | What it controls | Guidance |
| --- | --- | --- |
| **Connection name** | The display name shown in Agent Connections and source selectors. | Use a name people can recognize, such as `SharePoint Legal Knowledge` or `Salesforce Read Only`. |
| **Tool alias** | The short source handle used by Agents and source policy. | Keep it stable, lowercase, and specific. For example, `legal-sharepoint` is clearer than `docs`. |
| **MCP URL** | The endpoint for a custom MCP server. | Use an `https://` URL. `localhost` is allowed for development testing. |
| **Auth** | The authentication method for the provider. | Choose the narrowest method supported by the source. |
| **Mode** | Whether tools are limited to read-only or can read and write. | Start with **Read-only**. Use **Read / write** only when the Agent must create, update, upload, send, or delete. |
| **Skill instruction** | Instructions attached to the connection. | Explain what the source contains, when to use it, citation expectations, and what not to use it for. |
| **Tool Access** | The MCP tools this connection exposes to Agents. | Approve only the tools needed for the Agent's job. Read-only mode blocks tools that are known or likely to write. |
| **Evidence** | Whether source usage should be recorded for evidence. | Keep evidence enabled for governed, scheduled, or external-facing work. |
| **Required** | Whether an Agent should treat this source as mandatory. | Mark a source required when missing access would make the Agent output misleading or incomplete. |

## Authentication

Agent Connections support these authentication modes.

### None

Use **None** when the provider does not require a credential, when the source is built in, or when access is handled by the trusted environment around the MCP server.

The built-in Clear Ideas connection uses this pattern. It is always available, uses the `clearideas` alias, and does not require a separate credential.

### Access Token

Use **Access token** when the provider expects a bearer token, API key, or similar token credential.

To configure it:

1. Select the provider or **Custom MCP Server**.
2. Choose **Access token** in **Auth** when the provider allows auth selection.
3. Paste the token into **Access token**.
4. Select **Read-only** or **Read / write** based on what the token is allowed to do.
5. Select **Test** to confirm the token works and discover tools.
6. Approve the needed tools and save.

For updates, use **Replace access token**. Leaving the replacement field blank keeps the saved token unchanged.

Use short-lived or scoped tokens when possible. Rotate the token when a user leaves, a vendor changes, a token may have been exposed, or the connection no longer matches the Agent's purpose.

### OAuth 2.0

Use **OAuth 2.0** when the provider needs user or tenant consent and supports the OAuth authorization code flow.

To configure OAuth for a predefined provider:

1. Select the provider.
2. Review the OAuth client fields. Some providers are managed by Clear Ideas and only require the user to authorize their account.
3. If the provider requires your own OAuth app, paste the **OAuth client id** and, if required, the **OAuth client secret**.
4. Copy the **Callback URL** and add it to the provider's OAuth app settings.
5. Review the requested **OAuth scopes**.
6. Select **Connect & test** or **Connect**.
7. Complete the provider consent screen.
8. Confirm the connection is healthy, approve tools, and save.

To configure OAuth for **Custom MCP Server**, provide:

- **OAuth client id**
- **OAuth client secret**, if required by the MCP server
- **Authorization URL**
- **Token URL**
- **OAuth scopes**, separated by spaces
- the displayed **Callback URL** in the provider app settings

If an OAuth connection shows **needs consent**, **expired**, or **error**, open the connection and use **Reconnect**. Use **Revoke** when the connection should no longer have OAuth access.

## Tool Access

Tool Access is the approval layer between an Agent and a connection. A connection may discover many MCP tools, but Agents can only use the tools approved on the connection and then selected in the Agent's source policy.

Typical read tools include:

- list folders or records
- search content
- read documents or metadata
- fetch source details

Typical write tools include:

- create folders
- save or upload files
- update records
- send messages or webhooks
- delete or remove content

Use **Read-only** for research, analysis, summaries, and Q&A. Use **Read / write** only for Agents that are intentionally designed to produce side effects, such as filing generated reports or sending approved outputs.

## Use a Connection in an Agent

After saving a connection:

1. Open the Agent in the builder.
2. In the Agent source settings, add the saved connection.
3. Decide whether the Agent can use all approved tools or only specific tools.
4. Keep **Evidence** enabled when outputs need traceability.
5. Mark the source **Required** when the Agent should not run without it.
6. For each step, leave sources inherited, select a narrower source policy, or choose no sources.

This gives you two layers of control: the saved connection limits what the provider can expose, and the Agent source policy limits what a specific Agent or step can use.

## Health Checks and Status

Use **Test** to confirm that the source is reachable, credentials are valid, and MCP tools can be discovered. Test a connection whenever credentials, scopes, provider permissions, or the MCP server URL changes.

Common statuses include:

- **Healthy** means the last test succeeded.
- **Untested** means the connection has not been tested yet.
- **Error** means the last test or auth attempt failed.
- **OAuth authorization needs consent** means a user must complete OAuth consent.
- **OAuth authorization expired** means the OAuth grant must be reconnected.

Review connection health when:

- credentials change
- a provider reports an outage
- scheduled runs fail
- a source system changes permissions
- evidence metadata is incomplete

## Custom MCP Server Checklist

Before using a custom MCP server in production:

- confirm the MCP URL is stable and reachable over HTTPS
- choose the correct auth mode: **None**, **Access token**, or **OAuth 2.0**
- test with the same permissions the Agent will use
- approve only the required tools
- use **Read-only** unless the Agent must write
- make tool names and descriptions clear enough for Agents to choose correctly
- return stable source IDs, titles, URLs, updated timestamps, and hashes or lengths when evidence is enabled
- handle pagination, permission failures, and rate limits predictably
- separate development credentials from production credentials

## MCP Connector Readiness

Before using a third-party document MCP connector for production Agent runs, confirm that it handles:

- folder listing with many mixed files
- title and body search
- short and long document reads
- permission-denied cases
- recently modified documents
- pagination and rate limits
- stable source IDs, titles, source URLs, updated timestamps, and hashes or lengths where available

A connector may need an adapter wrapper when it omits evidence-grade metadata, over-fetches large documents, hides permission failures, or makes paging and rate-limit behavior unpredictable.

## Security Practices

- Prefer read-only credentials and read-only mode.
- Scope credentials to the source, tenant, folders, or records the Agent actually needs.
- Keep aliases stable so Agent source policy remains understandable.
- Do not approve destructive or write tools unless the Agent's purpose requires them.
- Re-test after changing scopes, tokens, OAuth app settings, or MCP server versions.
- Rotate or revoke credentials when access is no longer needed.

## Related Documentation

- [Source Connections and Tool Policy](/agents/source-connections-and-tool-policy)
- [Controlled Tools and Egress](/agents/controlled-tools-and-egress)
- [MCP Agent Authoring](/agents/mcp-agent-authoring)
- [Model Context Protocol](/ai/model-context-protocol)
- [Access Keys](/security/access-keys)