> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nextks.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Connectors
> Connect external MCP servers to NextKS and manage them from the dashboard. Connectors make tools available to the chat bot and the NextKS MCP.
## What are MCP connectors?
MCP connectors link external MCP servers — such as Jira, Notion, GitHub, or your own internal tools — to your NextKS organization. Once connected, the tools they expose become available in two places:
* **Chat bot** — Team members can use the tools by chatting with the NextKS bot in Slack or Teams
* **NextKS MCP** — Tools like Claude Desktop, Claude Code, and Cursor can access them through the [NextKS MCP](/guides/gateway-mcp) endpoint
There are two types of connectors:
Created by admins. Available to every member of the organization. Managed from **Admin → MCP Connectors**.
Created by individual users. Visible only to the user who created them. Managed from **MCP Connectors** in the sidebar.
## Adding a connector
1. Go to **Admin → MCP Connectors** in the sidebar
2. Click **Add Connector**
3. Fill in the connector details (see [Connector settings](#connector-settings) below)
4. Click **Save**
NextKS tests the connection before saving. If the MCP server is reachable, the connector is created and its tools are discovered automatically.
Organization connectors appear as read-only cards on every member's **MCP Connectors** page. Only admins can create, edit, or delete them.
1. Go to **MCP Connectors** in the sidebar
2. Click **Add Connector**
3. Fill in the connector details (see [Connector settings](#connector-settings) below)
4. Click **Save**
Personal connectors are visible only to you — other team members won't see them.
## Connector settings
When creating or editing a connector, you configure the following fields:
### Name
A display name for the connector (e.g., "Jira", "Internal Docs API"). Only letters, numbers, hyphens, underscores, and spaces are allowed.
The name is automatically converted to a lowercase namespace used to prefix tool names. For example, a connector named "My Jira Server" produces the namespace `my_jira_server`, and its tools appear as `my_jira_server_create_issue`, `my_jira_server_search`, etc.
Names that produce a namespace starting with `gateway_` are not allowed — this prefix is reserved for system tools.
### URL
The HTTP(S) endpoint of the MCP server. NextKS connects to this URL to discover tools and forward tool calls at runtime.
### API Key
An optional authentication key sent to the MCP server with every request. The key is encrypted at rest using AES-256-GCM and is never exposed in the dashboard after saving.
When editing a connector, leave this field blank to keep the existing key.
### AI Usage Notes
Optional free-text guidance (up to 1,000 characters) that tells the AI how and when to use this connector's tools. These notes are included in the tool description that the AI model sees, so they directly influence how the model decides to use the tools.
Good usage notes can significantly improve the AI's behavior. For example:
* *"Use this connector for project management queries. Always confirm with the user before creating or modifying issues."*
* *"This is the company HR system. Only use it when the user explicitly asks about HR topics like leave balances or org charts."*
* *"When searching, prefer short keyword queries over long sentences. Always include the project key."*
### Require tool approval
A toggle that controls whether tool calls need explicit user approval before execution. **Enabled by default.**
When enabled, the chat bot and the [NextKS MCP](/guides/gateway-mcp) will ask the user to approve each tool call before it runs. This is recommended for connectors that modify data or perform sensitive actions.
When disabled, tools are called automatically without approval.
## Authenticating with OAuth
Besides a static [API key](#api-key), a connector can authenticate with **OAuth** so it acts on each user's behalf without sharing a long-lived key. You choose the authentication type when you create the connector — it's fixed afterward.
| Auth type | What you provide |
| --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key** | A static Bearer key (the default — see [API Key](#api-key) above). |
| **OAuth (bring your own app)** | Pick a **Provider**, then paste your own OAuth app's **Client ID** and **Client Secret**. NextKS runs the consent flow against that provider. |
| **OAuth (MCP-native, auto-discovered)** | Nothing to paste — NextKS discovers the server's OAuth endpoints and registers a client for you automatically. After saving, you choose which **scopes** to request. |
### Bring your own OAuth app
With **OAuth (bring your own app)**, you register an OAuth application in your own provider account — Google Cloud or Microsoft Entra — and paste its credentials into NextKS. NextKS then runs the consent flow against *your* app, so tokens are issued by your organization and scoped to the permissions you grant.
Every bring-your-own-app connector uses the same redirect URI. Register this as the callback (redirect) URL in your provider's app:
```
https://app.nextks.com/api/oauth/outbound/callback
```
The connector dialog shows this **OAuth Callback URL** with a copy button, so you can paste it straight into your provider's app configuration.
1. In the [Microsoft Entra admin center](https://entra.microsoft.com), go to **App registrations → New registration**.
2. Under **Supported account types**, choose **Accounts in this organizational directory only (single tenant)**.
3. Add a **Web** platform redirect URI set to the callback URL above, then register the app.
4. Go to **Certificates & secrets → New client secret** and copy the secret's **Value** — not the **Secret ID**.
5. On the app's **Overview** page, copy the **Application (client) ID** and the **Directory (tenant) ID**.
6. Go to **API permissions**, add the Microsoft Graph **delegated** permissions your MCP server requires, then click **Grant admin consent** for your tenant.
7. Back in NextKS, create an **OAuth (bring your own app)** connector, choose **Microsoft 365**, and paste the **Application (client) ID**, **Client secret value**, and **Directory (tenant) ID**.
Single-tenant apps reject the shared sign-in endpoint, which is why the **Directory (tenant) ID** is required. Enter it as a GUID (e.g. `00000000-0000-0000-0000-000000000000`), not a domain like `contoso.onmicrosoft.com`.
For the NextKS-hosted **Microsoft 365 MCP server**, the required Microsoft Graph delegated permissions are:
| Permission | Purpose |
| --------------------- | ------------------------------------------------ |
| `Mail.Read` | Read the user's mail |
| `Mail.Send` | Send mail as the user |
| `Calendars.Read` | Read the user's calendar |
| `Calendars.ReadWrite` | Create and update calendar events |
| `User.Read` | Read the user's basic profile |
| `offline_access` | Keep the connection alive without re-authorizing |
1. In the [Google Cloud Console](https://console.cloud.google.com), go to **APIs & Services → Credentials → Create credentials → OAuth client ID**.
2. Choose **Web application** as the application type.
3. Under **Authorized redirect URIs**, add the callback URL above.
4. Create the client, then copy the **Client ID** and **Client Secret**.
5. Enable the APIs your MCP server uses, and add the scopes it requires on the **OAuth consent screen**.
6. Back in NextKS, create an **OAuth (bring your own app)** connector, choose **Google Workspace**, and paste the **Client ID** and **Client Secret**.
The exact permissions and scopes an OAuth app needs depend on the MCP server you're connecting — always check that server's documentation. For NextKS-provided servers, the index at [nextks-2-mcp-servers.vercel.app](https://nextks-2-mcp-servers.vercel.app) is authoritative.
### Connecting
After saving an OAuth connector, click **Connect** on its card. Your browser opens the provider's (or server's) consent page; approve it, and you're returned to NextKS with the connector marked **Connected**.
* **Bring-your-own-app:** save your Client ID and Client Secret first, then click Connect.
* **MCP-native:** select the scopes you want and register first, then click Connect.
### Connection status
OAuth connectors show a connection-status pill:
| Status | Meaning |
| -------------------------- | ----------------------------------------------------------------------------------------- |
| **Not connected** (gray) | Saved but not yet authorized — click **Connect**. |
| **Connected** (green) | Authorized and ready to use. |
| **Reconnect needed** (red) | The stored authorization expired or was revoked — click **Reconnect** to authorize again. |
### Disconnecting and reconnecting
**Disconnect** revokes the authorization at the provider and clears the stored tokens. Your saved bring-your-own-app credentials are kept, so you can reconnect in one click. **Reconnect** (shown when reconnection is needed) restarts the consent flow.
## Enabling and disabling connectors
Each connector has an **enable/disable toggle** on its card. When you disable a connector, its tools are immediately removed from both the chat bot and the NextKS MCP. No data is lost — you can re-enable it at any time.
When re-enabling, NextKS tests the connection first. If the MCP server is unreachable, the connector stays disabled and shows an error.
## Health monitoring
NextKS automatically monitors the health of all enabled connectors:
* **Automatic pings** — Every 5 minutes, NextKS pings each enabled connector to check if it's responding. The result is reflected in the status badge on the connector card.
* **Auto-refresh** — The connectors page polls for status changes every 30 seconds, so you see updates without refreshing the page.
### Status badges
| Badge | Meaning |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Connected** (green) | The connector is enabled and the MCP server is responding |
| **Disconnected** (gray) | The connector has been manually disabled |
| **Error** (red) | The last connection test failed (e.g., authentication error) |
| **Unreachable** (red) | The connector is enabled but the MCP server is not responding to health checks |
An "Unreachable" status does not disable the connector. NextKS continues to retry, and the status returns to "Connected" automatically when the server recovers.
## Tool discovery and caching
When a connector is created or re-enabled, NextKS connects to the MCP server and discovers all available tools. These tools are cached so they can be listed instantly in the chat bot and the NextKS MCP without reconnecting each time.
Tool caches are refreshed automatically:
* On every successful connection test (manual or automatic)
* During the daily maintenance cycle (every 24 hours)
If a connector's tools change on the MCP server side, you can force a refresh by toggling the connector off and on, or by editing and saving it.
## Deleting a connector
Click the delete button on a connector card. You'll be asked to confirm before the connector and its cached tool data are permanently removed.
Deleting a connector is permanent and cannot be undone. If you just want to temporarily stop using a connector, disable it instead.
## Organization vs. personal connectors
| | Organization | Personal |
| --------------------------- | ---------------------- | ------------------------ |
| **Who can create** | Admins only | Any member |
| **Who can see** | All members | Only the creator |
| **Who can edit/delete** | Admins only | Only the creator |
| **Managed from** | Admin → MCP Connectors | MCP Connectors |
| **Available in chat bot** | Yes, to all members | Yes, to the creator only |
| **Available in NextKS MCP** | Yes, to all members | Yes, to the creator only |
| **Audit logged** | Yes | No |
When a user connects via the chat bot or the NextKS MCP, they see tools from all organization connectors plus their own personal connectors.