Skip to main content

​
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 endpoint
There are two types of connectors:

Organization connectors

Created by admins. Available to every member of the organization. Managed from Admin → MCP Connectors.

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

​
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 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, 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.

​
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:
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, 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:
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 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:

​
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

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

When a user connects via the chat bot or the NextKS MCP, they see tools from all organization connectors plus their own personal connectors.