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

# NextKS MCP

> Connect Claude Desktop, Claude Code, and other MCP-compatible tools to all your organization's MCP servers through a single authenticated endpoint.

## What is the NextKS MCP?

The NextKS MCP is a single MCP server endpoint that gives any MCP-compatible tool access to every MCP connector your organization has configured — plus the built-in Q\&A knowledge base — without requiring you to set up each one individually.

Instead of adding Jira, Notion, and your internal APIs as separate MCP servers in every tool you use, you configure the NextKS MCP once. All tools — including the built-in Q\&A knowledge base and your external connectors — are discovered and called through a small set of meta-tools.

<CardGroup cols={2}>
  <Card title="One connection" icon="plug">
    A single URL gives your AI agent access to all org-wide MCP connectors, personal connectors, and the built-in Q\&A knowledge base.
  </Card>

  <Card title="On-demand discovery" icon="magnifying-glass">
    All tools are loaded into context only when requested — keeping context lean regardless of how many services your organization has.
  </Card>
</CardGroup>

## Authentication

The NextKS MCP supports two authentication methods: **OAuth** (recommended) and **API key**.

<Tabs>
  <Tab title="OAuth (Recommended)">
    OAuth lets you authenticate with your existing Slack or Microsoft Teams identity. Your MCP client handles the OAuth handshake automatically — you just add the URL and sign in when prompted.

    ### How it works

    1. You add the NextKS MCP URL to your tool (no API key needed)
    2. On first connection, your AI tool opens a browser window
    3. You sign in with your Slack or Teams account
    4. Authorization is granted automatically — you're connected

    <Note>
      If you're already signed in to NextKS in your browser, the authorization step is instant — no login prompt is shown.
    </Note>
  </Tab>

  <Tab title="API Key">
    If your AI tool does not support OAuth, you can authenticate with a personal API key instead.

    1. Go to the **Account** page in the NextKS dashboard
    2. Generate a personal API key
    3. Add the key as a `Bearer` token in the `Authorization` header

    <Warning>
      The NextKS MCP only accepts **personal API keys**. Silent keys (used internally by the NextKS bot) are rejected.
    </Warning>
  </Tab>
</Tabs>

## Installation

<Tabs>
  <Tab title="Claude Desktop">
    ### Step 1 — Add NextKS MCP

    1. Open Claude Desktop and go to **Settings → Connectors**
    2. Scroll to the bottom and click **Add custom connector**
    3. Enter the URL: `https://app.nextks.com/api/mcp/gateway`
    4. Click **Add**

    ### Step 2 — Authorize

    The first time Claude connects to the NextKS MCP, it opens your browser to a NextKS authorization page:

    1. Click **Sign in with Slack** or **Sign in with Microsoft Teams**
    2. Sign in with the same account you use for NextKS
    3. You are redirected back and Claude is authorized

    That's it — Claude now has access to your organization's tools.

    ### Enabling per conversation

    Once added, you can toggle the NextKS connector on or off for individual conversations:

    1. Click the **+** button in the lower left of your chat
    2. Select **Connectors**
    3. Toggle **NextKS** on
  </Tab>

  <Tab title="Claude Code">
    ### Step 1 — Add NextKS MCP

    Add the NextKS MCP to your Claude Code settings globally or per project.

    **Global** (`~/.claude/settings.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "nextks": {
          "url": "https://app.nextks.com/api/mcp/gateway"
        }
      }
    }
    ```

    ### Step 2 — Authorize

    The first time Claude Code connects, it opens your browser to a NextKS authorization page:

    1. Click **Sign in with Slack** or **Sign in with Microsoft Teams**
    2. Sign in with the same account you use for NextKS
    3. You are redirected back and Claude Code is authorized

    <Info>
      For API key authentication instead, add a `headers` block:

      ```json theme={null}
      {
        "mcpServers": {
          "nextks": {
            "url": "https://app.nextks.com/api/mcp/gateway",
            "headers": {
              "Authorization": "Bearer YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Info>
  </Tab>

  <Tab title="Other MCP clients">
    Add a new MCP server in your tool's settings with:

    * **URL:** `https://app.nextks.com/api/mcp/gateway`

    If your tool supports MCP OAuth, it will automatically prompt you to sign in on first connection.

    If your tool does not support OAuth, add your personal API key as a `Bearer` token in the `Authorization` header:

    * **Auth header:** `Authorization: Bearer YOUR_API_KEY`

    Replace `YOUR_API_KEY` with your personal API key from the **Account** page in the NextKS dashboard.
  </Tab>
</Tabs>

## Tools overview

When your tool connects to the NextKS MCP, it sees **5 meta-tools**. All services — including the built-in Q\&A knowledge base and your external connectors (Jira, Notion, etc.) — are discovered and called through these meta-tools:

| Meta-tool                     | Purpose                                                                                                   |
| ----------------------------- | --------------------------------------------------------------------------------------------------------- |
| `gateway_list_services`       | Discover available services and their tools                                                               |
| `gateway_tool_schema`         | Get the input schema for a specific tool                                                                  |
| `gateway_tool_call`           | Execute a tool by its namespaced name                                                                     |
| `gateway_search_kb`           | Semantic search across the knowledge base (published Q\&A, meeting minutes, and your own private content) |
| `gateway_get_pending_results` | Retrieve the result of a slow tool call that returned `pending`                                           |

The first three are the discover → inspect → call core for external connector tools; `gateway_search_kb` and `gateway_get_pending_results` are called directly. This on-demand discovery keeps the agent's context lean — tool schemas are only loaded when actually needed, regardless of how many services your organization has.

## The meta-tools

### `gateway_list_services`

Discover which services are connected and which tools each one provides. **Call this first** whenever the agent needs to know what tools are available. This lists both the built-in Q\&A knowledge base and any external connectors your organization has configured.

```
Call: gateway_list_services()

Output:
Connected services (3 available, 0 unavailable):

nextks_qa — NextKS Q&A — ticket management and knowledge base
  Available tools: nextks_qa_create_ticket, nextks_qa_get_ticket,
  nextks_qa_search_tickets, nextks_qa_update_ticket, ...

jira — Jira Cloud project management
  Available tools: jira_create_issue, jira_search_issues, jira_update_issue

notion — Notion workspace
  Available tools: notion_create_page, notion_search
```

The Q\&A service (`nextks_qa`) is always available. External services that are temporarily unreachable are listed separately with an `[UNAVAILABLE]` tag — they do not block the rest.

### `gateway_tool_schema`

Get the input schema for a specific tool before calling it. Provide the **namespaced tool name** exactly as shown by `gateway_list_services`.

```
Call: gateway_tool_schema(tool_name: "jira_create_issue")

Output:
{
  "type": "object",
  "properties": {
    "project": { "type": "string", "description": "Project key (e.g. ENG)" },
    "summary":  { "type": "string", "description": "Issue title" },
    "description": { "type": "string" }
  },
  "required": ["project", "summary"]
}
```

If the connector requires approval, the schema is prefixed with `[REQUIRES APPROVAL]` as a reminder to confirm with the user before proceeding.

### `gateway_tool_call`

Execute a tool by its namespaced name with the arguments defined by its schema.

```
Call: gateway_tool_call(
  tool_name: "jira_create_issue",
  arguments: { "project": "ENG", "summary": "Fix login timeout" }
)

Output: (the tool's response, passed through unchanged from the downstream MCP)
```

NextKS handles routing to the correct downstream MCP server, authentication, and error recovery automatically.

<Warning>
  If `gateway_list_services` shows a service tagged `[REQUIRES APPROVAL]`, always confirm with the user before calling `gateway_tool_call` for that service. This setting is configured per connector in the NextKS dashboard and signals that the connector performs write operations or other consequential actions.
</Warning>

### `gateway_search_kb`

Semantic search across your organization's knowledge base — published Q\&A answers, meeting minutes, and the caller's own private content. Call it directly (no `gateway_tool_schema` step needed). Pass one or more `queries`; multiple queries run in parallel and are returned in input order. Optionally restrict the sources with `source_types` (e.g. `["qna"]`).

```
Call: gateway_search_kb({ "queries": ["login issues", "SSO setup"] })

Output: ranked matches per query (title, snippet, source type), grouped by query in input order.
```

### `gateway_get_pending_results`

Most `gateway_tool_call` invocations return inline. A slow tool instead returns `{"status":"pending","job_id":...}` — it is running in the background. Call `gateway_get_pending_results` to retrieve the result once it is ready.

```
Call: gateway_tool_call("slow_report_tool", { ... })
  → {"status":"pending","job_id":"job_abc123"}

Call: gateway_get_pending_results()
  → the completed result(s), or a still-in-progress status (retry in a few seconds)
```

Each ready result is returned once — it is consumed on retrieval, so repeated polls won't deliver duplicates.

## Typical interaction flow

A complete example showing how an AI agent discovers and uses tools from multiple services:

```
User: "Search for any open Jira tickets about login issues and summarize
       them as a Q&A ticket."

Agent:
  1. gateway_list_services()
     → discovers nextks_qa and jira services with their tools

  2. gateway_search_kb({ "queries": ["login issues"] })
     → semantic search across the knowledge base (published Q&A answers,
       meeting minutes, memos, and the caller's own private notes); multiple
       queries in one call are executed in parallel and returned in input order.
       Use `source_types: ['qna']` if you want to restrict to Q&A tickets.

  3. gateway_tool_schema("jira_search_issues")
     → learns the required parameters for Jira search

  4. gateway_tool_call("jira_search_issues", { "query": "login" })
     → receives matching Jira issues

  5. gateway_tool_call("nextks_qa_create_ticket", { "title": "Login issues summary", ... })
     → creates the Q&A ticket
```

All tools — both Q\&A and external — are accessed through the same meta-tool layer. The agent calls `gateway_list_services` once to discover everything, then uses `gateway_tool_schema` and `gateway_tool_call` as needed.

## Built-in Q\&A tools

The Q\&A knowledge base (`nextks_qa`) is a built-in service that is always available through the NextKS MCP. It does not appear as a connector in the dashboard — it is automatically included when the agent calls `gateway_list_services`.

The 13 Q\&A tools cover the full ticket lifecycle: creating tickets, submitting and accepting answers, managing participants, and more. For knowledge-base search across Q\&A, meeting minutes, memos, and your own private content, use the `gateway_search_kb` meta-tool (see the example above). For full Q\&A documentation, see [Q\&A Tickets](/guides/qna-tickets).

## Managing connectors

The external tools visible through the NextKS MCP are managed from the **MCP Connectors** page in the NextKS dashboard. Organization admins create connectors that are available to all members, and individual users can add personal connectors visible only to them.

For full details on adding connectors, configuring AI usage notes, approval settings, and health monitoring, see [MCP Connectors](/guides/mcp-connectors).