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

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
• Controlled Tools and Egress
• MCP Agent Authoring
• Model Context Protocol
• Access Keys