> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parlehub.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Integrations to ParleHub: Confluence and Custom MCP Tools
> Pick a system from the Integrations gallery, choose who its credential belongs to, and enable it on the projects that need it.
Integrations let the ParleHub agent do things outside a conversation — search Confluence, look up a Jira ticket, call your own service — by connecting it to a system your organization already uses.
You pick an integration from the **gallery** in **Organization Settings → Integrations**. Each card is a system ParleHub knows how to connect to, with its server address and authentication method already filled in — you supply only what is genuinely yours: a credential, or an approval at the provider.
* **Confluence** is a branded card. Its server address (Atlassian's own hosted MCP server) and authentication (OAuth 2.0) are fixed by the card, so there is nothing to type before you approve access. See [Connecting Confluence](/tools/confluence) for what it can do and which scope to pick.
* **Custom MCP Tool** is the card for everything else that runs an **MCP server** (an external service that speaks the Model Context Protocol) but has no card of its own. You give ParleHub its address and how to authenticate, and it behaves exactly like any other integration from then on.
Setting one up has two levels, and both are deliberate:
1. **Connect it once for your organization.** Only **Org Admins** can do this, so project members cannot point the agent at arbitrary external services.
2. **Enable it per project.** A connected integration is available to nothing until a project switches it on — so an integration that reaches sensitive systems can be limited to the projects that should have it.
ParleHub calls the other system **from the server side**, never from anyone's browser, and the credentials you store are never sent to a client.
**You'll need:** to be an **Org Admin** in ParleHub, and — for the Custom MCP Tool card — the MCP server's **HTTPS URL** plus whatever it needs for authentication (an API key or token, or an OAuth 2.0 application at the provider).
**Integrations are part of your plan.** If yours doesn't include them, the gallery says so and names the plan that does. See [Plans & Billing](/plans-and-billing) for the count each tier includes. Anything you've already connected stays listed, editable and removable either way — losing the plan never strands a credential.
## Choosing who the credential belongs to
A card that supports more than one scope asks **who this connection is for** when you add it: **Organization**, **Project**, or **User** (each member connects their own account). The choice decides who authenticates, whose access the agent uses for that call, and who can end up reading the result — it's the single most consequential decision in setting an integration up, so it has [its own page](/tools/integration-scopes). Read it before you connect anything that reaches content not everyone in your organization should see.
Confluence is the only card today that offers all three; Custom MCP Tool offers Organization and Project. A card only ever offers the scopes it declares support for — a personal mailbox or calendar integration, for instance, would never offer Organization scope, because a shared inbox credential isn't a sensible thing to hand every project's agent.
## Part 1 — Connect an integration to your organization
### What happens
You pick an integration from the gallery and fill in whatever it still needs. Before saving, ParleHub checks the address is safe and that the other system actually answers — so a typo, a firewalled server, or an address that points somewhere it shouldn't is caught now rather than mid-conversation. That check runs on every integration, **including one whose address was filled in for you** — a pre-filled address gets no special treatment.
Go to **Organization Settings → Integrations** and select **Add integration**.
Selecting a card opens its detail page: what it is, what it gives your agents, what access it will ask for, and the address it connects to. Select **Add** to open the connect form.
* **Name** — a friendly name your team will recognize in the project tool list (e.g. `Jira MCP`).
* **Description** — optional; a short note on what this integration lets the agent do.
* **Server URL** — for the Custom MCP Tool card, the MCP server's HTTPS base URL, e.g. `https://mcp.example.com`. A branded card fills this in for you.
* **Who it's for** — for a card that offers more than one scope, choose Organization, Project, or User. See [Choosing a scope](/tools/integration-scopes).
See [Part 2](#part-2-authentication). Pick **API key or token in a header** if you already hold a key, or **OAuth 2.0** if the provider wants you to approve access instead.
Select **Connect**.
### What ParleHub checks before saving
* The URL **must be HTTPS**. Plain `http://` is rejected.
* The URL **must not point to a private, internal, or loopback address** — `localhost`, `10.x`, `192.168.x`, link-local, and cloud metadata addresses are all refused, including when a public-looking hostname resolves to one. This protects your cloud environment from being reached through the agent.
* The server **must answer** a quick connection check within a few seconds. If it does not, you will see *"MCP server is not reachable"* or *"MCP server did not respond within the timeout"*, and nothing is saved.
Registering, editing, rotating secrets on, and removing an organization's connection to an integration is **Org Admin only**. Connecting a **Project** scope credential is that project's **Project Admin**; connecting a **User** scope credential is the member themselves — see [My Integrations](/tools/my-integrations).
## Part 2 — Authentication
Choose the option that matches what the provider gives you. Confluence always uses OAuth 2.0; Custom MCP Tool offers both.
Use this when you already hold a key or token from the provider and it's sent on every request.
1. With **API key or token in a header** selected, use **Add header** for each header the server expects.
2. Enter the **header name** (e.g. `Authorization` or `X-Api-Key`) and its **value** (e.g. `Bearer abc123…`).
3. Tick **Secret** for anything that's a credential. A secret value is stored in your organization's vault and **can't be viewed again** after saving — only replaced.
4. Select **Connect**.
To replace a key later, find the header on the integration's card and select **Rotate secret**, enter the new value, and select **Save**. The old value is superseded immediately.
Header-based authentication is available only at **Organization** scope — a per-project or per-member secret header has nowhere for that project or member to type one, so **Project** and **User** scope integrations must use OAuth.
Use this when the provider wants an administrator (or, for Project/User scope, the connecting project or member) to approve access rather than hand out a static key.
For an integration connected at **Organization** scope, ParleHub holds one connection shared by every project it's enabled for — so the agent keeps working when nobody is online. A **Project** or **User** scoped integration instead keeps a separate connection per project or per member, each connected from that project's Tools tab or that member's My Integrations page. Whoever approved a given connection is recorded and shown on its card.
1. Select **OAuth 2.0** in the connect form and select **Connect**. No credentials are entered at this point.
2. On the new card, select **Find settings automatically**. For a server that supports it, ParleHub works out every setting from the URL alone — including registering an application with the provider on your behalf — and reports what it found. Confluence's server always resolves this way.
3. If discovery only gets part-way, the manual form opens **pre-filled with whatever was found**. Fill in the rest from the application you registered with the provider:
* **Authorization endpoint** and **Token endpoint** — from the provider's OAuth documentation.
* **Client ID**, and **Client secret** if the provider issued one (leave blank for a public client).
* **Scopes** — space-separated. Ask only for what the integration actually needs. A branded card like Confluence fixes its own scopes and skips this step.
Then select **Save OAuth settings**.
4. Select **Connect**. You're sent to the provider to approve access, and returned to ParleHub with the result. The card shows **Connected**, along with the account, who connected it, the granted scopes, and when the access was last renewed.
### Two OAuth states that need your attention
ParleHub renews access automatically, but two states do not resolve themselves:
| State | What it means | What to do |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| **Reconnect required** | The provider is no longer accepting the stored authorization, and the integration is failing for every project or member using that connection. | Select **Reconnect** to approve it again. Org Admins are notified when this happens. |
| **Reconnect recommended** | The connection still works, but it belongs to a member who is no longer active. | Reconnect it under a current account before their access at the provider is removed. |
## Part 3 — Enable an integration on a project
### What happens
Connecting an integration at Organization or Project scope makes it *available*; it does nothing in any project until that project switches it on. A **User** scoped integration works a little differently — see [My Integrations](/tools/my-integrations).
Open the project and go to the **Tools** tab.
Every integration connected for your organization is shown, with its server URL underneath.
The change takes effect on the next message; there's nothing to save. For a **Project** scoped integration, toggling it on shows the project as **not connected** until a Project Admin connects that project's own account.
Toggle it **off** at any time to remove it from that project. Everyone on the project sees the same list — project members and Project Admins can see **which** integrations are enabled (shown as **Enabled** / **Disabled**), but only an **Org Admin** can change the toggles.
Integrations work in **project conversations only**. Personal conversations have no project, so they get neither integrations nor [file tools](/projects/file-tools).
## Part 4 — Using an integration in a conversation
Once an integration is enabled, the agent discovers what it can do automatically — you don't describe it to the agent. Ask for what you want in plain language (*"what's on the Q3 roadmap page?"*) and the agent decides whether to use it.
While a tool call is in flight the message shows a short activity line — an external tool can take tens of seconds. If an integration is unreachable or its credentials have stopped working, the agent is told the call failed and carries on with the rest of the turn — one broken integration costs a tool call, not the conversation.
For a **User** scoped integration, whose credential answers the call depends on who's asking — see [Choosing a scope](/tools/integration-scopes) for what that means when the conversation is shared.
### What gets recorded
Every call is written to your organization's [audit log](/security/audit-log) against the user, the conversation and the tool. The record covers **what happened, not what was said**: the tool's name and category, whether it succeeded, failed or was cancelled, how long it took, and the size of the request and response.
The request and response payloads themselves are deliberately never stored. A tool's arguments routinely contain your own documents, and ordinary writes to the audit log are rejected — an entry can't be edited or deleted through ParleHub or by an ordinary database write — so keeping payloads there would put a second copy of your content somewhere ParleHub's own deletion paths can't reach.
## Part 5 — Maintaining an integration
**None of this depends on your plan.** If your plan stops including integrations you can't connect a new one, but everything below stays available — so an organization is never left holding a credential in ParleHub's vault that it can't take back out.
| Task | Where | Effect |
| ------------------------------ | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Replace an API key or token | Integration card → **Rotate secret** on that header | New value stored in the vault; takes effect on the next call |
| Re-approve an OAuth connection | Integration card → **Reconnect** | Sends you back to the provider to approve again |
| Drop one connection | Integration card → **Disconnect** | Takes effect immediately: the stored authorization is revoked at the provider, the secret is deleted from the vault, and the integration stops working until reconnected |
| Remove an integration entirely | Integration card → **Remove** | Disappears from every project immediately, but its credentials are **kept for 14 days** — add it back inside that window and nobody has to reconnect. After 14 days, every credential it held is revoked at the provider and deleted from the vault |
**Remove** and **Disconnect** are worded apart on purpose. Disconnect is unambiguous and immediate; Remove gives you a two-week window to change your mind before the credentials are actually destroyed.
## Troubleshooting
| Symptom | Likely cause | Fix |
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| "MCP server URL must use HTTPS" | The URL starts with `http://` | Use the server's HTTPS address |
| "must not point to a private, loopback, link-local, or metadata address" | The URL is (or resolves to) an internal address | ParleHub only reaches MCP servers on the public internet — publish the server, or use a provider-hosted one |
| "MCP server hostname could not be resolved" | Typo in the hostname, or the DNS record doesn't exist publicly | Re-check the URL |
| "MCP server is not reachable" / "did not respond within the timeout" | Server down, or blocking ParleHub at its firewall | Confirm the server is up and reachable from outside your network, then connect again |
| Connected fine, but the agent says it has no such tool | It isn't enabled on **this** project, you're in a personal conversation, or (User scope) nobody in the project has connected their own account yet | Enable it on the project's **Tools** tab; start the chat inside a project; connect from [My Integrations](/tools/my-integrations) |
| Tool list toggles are greyed out | You're not an Org Admin | Ask an Org Admin to enable it — members can view but not change |
| A card shows **Reconnect required** | The provider rejected the stored authorization (revoked, expired, or scopes changed) | Select **Reconnect** and approve again at the provider |
| A card shows **Reconnect recommended** | The connection belongs to a deactivated member | Reconnect it under a current admin's account |
| "Find settings automatically" only partly works | The server doesn't publish full OAuth metadata | Complete the remaining fields manually — what was found is already filled in |
| Tool calls fail with an authorization error | The key was revoked at the provider, or scopes are too narrow | Rotate the secret, or reconnect with the scopes the integration needs |
| "already enabled for this project" | It's on already | No action needed — refresh the Tools tab |
| "Connecting integrations is not included in your ParleHub plan" | Your plan doesn't include integrations, or you already have as many as it includes | The message names the plan that includes them. Everything you've connected stays listed and removable |
| **Add integration** is missing | Your plan doesn't include integrations, or you're not an Org Admin | See the panel at the top of the Integrations tab |
Still stuck? Contact ParleHub support with your organization name, the integration's name, and (for Custom MCP Tool) the server URL you're connecting.