> ## 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.

# Set Up Custom MCP Tools for Your Organization

> Register an MCP server once for your organization, authenticate it with a header key or OAuth 2.0, and enable it on the projects that need it.

MCP tools let the ParleHub agent do things outside a conversation — look up a ticket in Jira, query an internal knowledge base, call your own service — by connecting it to an **MCP server** (an external service that speaks the Model Context Protocol).

Setting one up has two levels, and both are deliberate:

1. **Register the server once for your organization.** You supply its URL and how it authenticates. Only **Org Admins** can do this, so project members cannot point the agent at arbitrary external services.
2. **Enable it per project.** A registered tool is available to nothing until you switch it on for a specific project — so a tool that reaches sensitive systems can be limited to the projects that should have it.

ParleHub calls the MCP server **from the server side**, never from anyone's browser, and the credentials you store are never sent to a client.

<Note>
  **You'll need:** to be an **Org Admin** in ParleHub, the MCP server's **HTTPS URL**, and whatever it needs for authentication (an API key or token, or an OAuth 2.0 application at the provider).
</Note>

## Part 1 — Register an MCP server

You tell ParleHub where the MCP server lives and how to authenticate to it. Before saving, ParleHub checks the URL is safe and that the server actually answers — so a typo or a firewalled server is caught now rather than mid-conversation.

<Steps>
  <Step title="Open MCP Tools settings">
    Go to **Organization Settings → MCP Tools** and select **Add tool**.
  </Step>

  <Step title="Choose Generic MCP Tool">
    This connects any MCP-compatible server.
  </Step>

  <Step title="Describe the server">
    * **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 tool lets the agent do.
    * **Server URL** — the MCP server's HTTPS base URL, e.g. `https://mcp.example.com`.
  </Step>

  <Step title="Choose how the server authenticates">
    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.
  </Step>

  <Step title="Register the tool">
    Select **Register tool**.
  </Step>
</Steps>

### 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.

<Warning>
  Registering, editing, rotating secrets on, and removing MCP tools is **Org Admin only**.
</Warning>

## Part 2 — Authentication

Choose the option that matches what the provider gives you.

<Tabs>
  <Tab title="API key or token in a header">
    Use this when you already hold a key or token from the provider and it is 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 is a credential. A secret value is stored in your organization's vault and **cannot be viewed again** after saving — only replaced.
    4. Select **Register tool**.

    To replace a key later, find the header on the tool's card and select **Rotate secret**, enter the new value, and select **Save**. The old value is superseded immediately.
  </Tab>

  <Tab title="OAuth 2.0">
    Use this when the provider wants an administrator to approve access rather than hand out a static key. ParleHub holds **one connection per tool, shared by every project it is enabled for** — so the agent keeps working when nobody is online. Whoever approved it is recorded and shown on the card.

    1. Select **OAuth 2.0** in the registration form and select **Register tool**. No credentials are entered at this point.
    2. On the new tool's 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.
    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 tool actually needs.

       Then select **Save OAuth settings**.
    4. Select **Connect**. You are 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.
  </Tab>
</Tabs>

### 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 tool is failing for every project. | 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 a tool on a project

Registering a tool makes it *available* to your organization; it does nothing until you enable it on a project. Only then can the agent see and call it in that project's conversations.

<Steps>
  <Step title="Open the project's Tools tab">
    Open the project and go to the **Tools** tab.
  </Step>

  <Step title="Find the tool">
    Every tool registered for your organization is shown, with its server URL underneath.
  </Step>

  <Step title="Toggle it on">
    The change takes effect on the next message; there is nothing to save.
  </Step>
</Steps>

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** tools are enabled (shown as **Enabled** / **Disabled**), but only an **Org Admin** can change the toggles.

<Note>
  MCP tools work in **project conversations only**. Personal conversations have no project, so they get neither MCP tools nor [file tools](/projects/file-tools).
</Note>

## Part 4 — Using the tool in a conversation

Once a tool is enabled, the agent discovers what it can do automatically — you do not describe the tool to it. Ask for what you want in plain language (*"what's the status of ticket ABC-123?"*) 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 a tool 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 tool costs a tool call, not the conversation.

### 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 — so keeping payloads there would put a second copy of your content somewhere ParleHub's own deletion paths cannot reach.

## Part 5 — Maintaining a registered tool

| Task                           | Where                                        | Effect                                                                        |
| ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------- |
| Replace an API key or token    | Tool card → **Rotate secret** on that header | New value stored in the vault; takes effect on the next call                  |
| Re-approve an OAuth connection | Tool card → **Reconnect**                    | Sends you back to the provider to approve again                               |
| Drop an OAuth connection       | Tool card → **Disconnect**                   | The stored authorization is revoked; the tool stops working until reconnected |
| Remove a tool entirely         | Tool card → **Remove**                       | Deregisters it for the whole organization and every project using it          |

## 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 does not 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 register again                       |
| Registered fine, but the agent says it has no such tool                  | The tool is not enabled on **this** project, or you are in a personal conversation   | Enable it on the project's **Tools** tab; start the chat inside the project                                 |
| Tool list toggles are greyed out                                         | You are not an Org Admin                                                             | Ask an Org Admin to enable it — members can view but not change                                             |
| Tool card shows **Reconnect required**                                   | The provider rejected the stored authorization (revoked, expired, or scopes changed) | Select **Reconnect** and approve again at the provider                                                      |
| Tool 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 does not 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 tool needs                                              |
| "already enabled for this project"                                       | The tool is on already                                                               | No action needed — refresh the Tools tab                                                                    |

Still stuck? Contact ParleHub support with your organization name, the tool's name, and the MCP server URL you are connecting.