Pencel

Appearance

Setting Up Connections ​

Connections let your agents interact with external tools and services — Slack, Notion, databases, file systems, and more. This guide walks you through adding a connection, testing it, and configuring how agents use it.

What is a connection? ​

A connection links Pencel to an outside service. Once connected, your agents can read data from and write data to that service during workflow runs or chat sessions. All credentials are stored securely on your machine using your operating system's keychain — they never leave your computer.

Step-by-step: Add a connection ​

1. Open Settings ​

Click Settings in the left sidebar to open the settings panel. Navigate to the Connections section.

2. Browse the integration catalog ​

Pencel includes a catalog of built-in integrations. Click Add Connection to open the catalog. You see a list of available services organized by skill category:

  • Browser — Web fetching and browser automation (Web Fetch, Playwright)
  • Search — Web and document search (Brave Search)
  • Code — Source control and filesystem access (GitHub, Filesystem)
  • Data — Database access (PostgreSQL, SQLite, Redis)
  • Memory — Persistent knowledge graph
  • Custom — Imported and custom MCP servers

Additional integrations are available for productivity and operations tools such as Slack, Notion, Google Workspace, Asana, Atlassian, Linear, Monday.com, Stripe, SAP S/4HANA, and Workday.

3. Select an integration ​

Click on the service you want to connect. This opens a configuration form specific to that integration.

4. Fill in credentials ​

Each integration requires different credentials. Common types include:

  • API key — A single key string provided by the service. Paste it into the API Key field.
  • OAuth — Click the authorization button, sign in to the service in your browser, and grant Pencel access.
  • Connection string — For databases, provide a connection string with host, port, database name, and credentials.

WARNING

Double-check that you are using the correct credential type. Some services offer multiple types of API keys (test vs. production, read-only vs. full access). Use the key that matches the level of access your agents need — and no more.

5. Test the connection ​

After entering credentials, click Test Connection. Pencel attempts to reach the service and reports back:

  • Success — The connection works. You see the response time and the number of available tools.
  • Failure — Something went wrong. Check the error message for details (see troubleshooting below).

6. Configure activation mode ​

The activation mode controls when this connection is available to agents:

ModeHow it works
Auto-connectThe connection activates automatically when any agent starts a task. Best for essential services that every workflow needs.
When relevantPencel activates the connection only when an agent's task is related to this service. Reduces unnecessary connections and keeps costs down.
ManualThe connection only activates when you explicitly select it or when a workflow lists it as a required tool. Gives you the most control.

TIP

Start with When relevant for most connections. This balances convenience with efficiency. Use Auto-connect only for services your agents need on nearly every task, like a primary database or company-wide Slack workspace.

7. Save ​

Click Save to store the connection. It appears in your connections list with a status indicator showing whether it is currently connected, disconnected, or has an error.

Managing existing connections ​

From the Connections section in Settings, you can:

  • Connect / Disconnect — Toggle a connection on or off without deleting the credentials. Useful for maintenance windows.
  • Edit — Update credentials or change the activation mode.
  • Delete — Remove the connection entirely, including stored credentials.

The connection card shows key information at a glance:

  • Connection name and service type
  • Status (connected, disconnected, error, connecting, or needs reauthorization)
  • Number of available tools
  • Activation mode

Troubleshooting common errors ​

"Authentication failed" or "Invalid API key" ​

  • Confirm that you copied the full key with no extra spaces.
  • Check that the key has not expired. Many services rotate keys periodically.
  • Verify you are using the correct key type (production vs. sandbox, read vs. write).

"Connection timed out" ​

  • Check your internet connection.
  • Verify the service is not experiencing an outage (check the provider's status page).
  • If connecting to a self-hosted database, confirm the host and port are correct and that your firewall allows the connection.

"Permission denied" ​

  • The credentials you provided may not have the required permissions. Check the service's settings to ensure your API key or account has the necessary access level.
  • For OAuth connections, you may need to re-authorize with expanded permissions.

"SSL/TLS error" ​

  • This usually occurs with self-hosted services using self-signed certificates. Check your service's SSL configuration.

INFO

When a connection fails, Pencel records the error details. Click the connection card to see the full error message and timestamp. This information is helpful if you need to contact the service provider for support.

How agents use connections ​

When an agent runs a task (either through a workflow or in chat action mode), it sees the tools provided by active connections. Each tool from a connection appears with a clear label indicating which service it belongs to.

Agents can only use connection tools when operating in action mode. In chat mode, agents do not have access to any tools — including connection tools. See Using Chat for more on the difference between modes.

If a workflow lists specific connections as required tools, Pencel checks that those connections are active before starting the run. If a required connection is missing or disconnected, the run will not start and you see a clear error message explaining what is needed.

Tips for managing connections ​

  • Use descriptive names. If you have multiple connections to the same service (e.g., staging and production databases), name them clearly.
  • Review permissions regularly. Periodically check that each connection has only the permissions it needs. Remove connections that are no longer used.
  • Test after credential rotation. Whenever you rotate API keys or tokens, update the credentials in Pencel and run a test to confirm everything still works.
  • Check the run's event log. If an agent fails to use a connection during a run, the run's event log on the Jobs page shows the exact error the agent encountered.

Next steps ​