### README

# Mintlify Starter Kit

Click on `Use this template` to copy the Mintlify starter kit. The starter kit contains examples including

- Guide pages
- Navigation
- Customizations
- API Reference pages
- Use of popular components

### Development

Install the [Mintlify CLI](https://www.npmjs.com/package/mintlify) to preview the documentation changes locally. To install, use the following command

```
npm i mintlify
```

Run the following command at the root of your documentation (where docs.json is)

```
mintlify dev
```

### Publishing Changes

Install our Github App to auto propagate changes from your repo to your deployment. Changes will be deployed to production automatically after pushing to the default branch. Find the link to install on your dashboard.

#### Troubleshooting

- Mintlify dev isn't running - Run `mintlify install` it'll re-install dependencies.
- Page loads as a 404 - Make sure you are running in a folder with `docs.json`

---

### Installation

---
title: Installation
description: Install Klavis SDK or use REST API directly
icon: wrench
---

## SDK Installation

<CodeGroup>
```bash Python
pip install klavis
```

```bash TypeScript
npm install klavis
```
</CodeGroup>

## REST API

```bash
curl -X POST "https://api.klavis.ai/mcp-server/instance/create" \
  -H "Authorization: Bearer YOUR_KLAVIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serverName": "Gmail", "userId": "user123"}'
```

---

### Introduction

---
title: "Paving the road to AGI"
mode: "wide"
---

> *We build the worlds* <br />
> *where intelligence learns to act* <br />
> *one environment* <br />
> *one trajectory* <br />
> *one step at a time*

---

### Quickstart

---
title: Quickstart
description: Let your agent connect any tools reliably in minutes via MCP
icon: rocket
mode: "wide"
---

## Strata
One MCP server that lets AI agents handle any tools progressively.

<Tabs>
  <Tab title="UI">
    <Steps>
      <Step title="Open Dashboard">
        Go to your <a href="https://www.klavis.ai/home/mcp-servers">Dashboard</a>.
        
        <Tip>
        Klavis enables all integrations for you by default. Click the ellipsis button if you want to disable a specific integration.
        </Tip>
        
        <img
          className="block dark:hidden"
          src="/images/get-started/quickstart/strata_ui.png"
          alt="Strata UI Dashboard"
        />
        <img
          className="hidden dark:block"
          src="/images/get-started/quickstart/strata_ui.png"
          alt="Strata UI Dashboard"
        />
      </Step>
      <Step title="Authenticate">
        Complete authentication by clicking the **"Authorize"** button. Most of the applications has OAuth support. Just follow the OAuth flow to authorize them.
        
        Some applications might need you to provide API keys or other kinds of secrets to authorize.

        Some applications don't have **"Authorize"** buttons. It means they don't require authentication and you can access them directly.

        <Tip>
        We also provide an authentication handler tool in MCP that will prompt to authenticate when if you didn't authorize them.
        </Tip>

        <img
          className="block dark:hidden"
          src="/images/get-started/quickstart/oauth.png"
          alt="Strata OAuth Example"
        />
        <img
          className="hidden dark:block"
          src="/images/get-started/quickstart/oauth.png"
          alt="Strata OAuth Example"
        />
      </Step>
      <Step title="Use in your app">
        Add to your favorite MCP-supported clients, such as Cursor, Claude Code, VS Code, ChatGPT, etc.

        To get the MCP server URL and access token, click the **"Add to Other Clients"** button on the top right corner of the dashboard.

        <Tip>
        Both the URL with access token and the direct URL provide you with the **same** MCP. But it's recommended to use the URL with access token as it's a more secure way to connect.

        DO NOT share your access token or direct URL publicly as they provide access to your connected accounts and data.
        </Tip>

        <img
          className="block dark:hidden"
          src="/images/get-started/quickstart/url.png"
          alt="Strata URL"
        />
        <img
          className="hidden dark:block"
          src="/images/get-started/quickstart/url.png"
          alt="Strata URL"
        />
      </Step>
    </Steps>
  </Tab>
  <Tab title="API">
    <Info>

    **Prerequisites** Before you begin, [create an account](https://www.klavis.ai/home/api-keys) and get the API Key.

    </Info>
    <Steps>
      <Step title="Install the SDKs">
        <CodeGroup>
          ```bash pip
          pip install klavis
          ```

          ```bash npm
          npm install klavis
          ```
        </CodeGroup>
      </Step>
      <Step title="Create Strata MCP Server">
        <Tip>
        `userId` specifies whose connected accounts and data you are accessing in Klavis. It should be a unique id for yourself, your team, or your organization.
        </Tip>
        <CodeGroup>
          ```bash Curl
          curl -X POST "https://api.klavis.ai/mcp-server/strata/create" \
            -H "Authorization: Bearer YOUR_KLAVIS_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "userId": "user123",
              "servers": ["Gmail", "YouTube"]
            }'
          ```

          ```python Python
          from klavis import Klavis
          from klavis.types import McpServerName

          klavis_client = Klavis(api_key="YOUR_KLAVIS_API_KEY")

          response = klavis_client.mcp_server.create_strata_server(
              user_id="user123",
              servers=[McpServerName.GMAIL, McpServerName.YOUTUBE],
          )
          ```

          ```typescript TypeScript
          import { Klavis } from 'klavis';

          const klavis = new Klavis.Client({ apiKey: 'YOUR_KLAVIS_API_KEY' });
          const strata = await klavis.strata.create({
            userId: 'user123',
            servers: ['GMAIL', 'YOUTUBE'],
          });
          ```
        </CodeGroup>
        <Info>
        **Response Information**: The API returns:
        - `strataServerUrl`: The URL you'll use to connect your MCP client to the Strata MCP Server
        - `oauthUrls`: Authorization links for services that require OAuth authentication
        - `apiKeyUrls`: Links to configure API keys for services that use API key authentication
        </Info>
        <Card title="API Reference" icon="magnifying-glass" href="/api-reference/strata/create" horizontal>
          Full Strata API endpoints
        </Card>
      </Step>
      <Step title="Authenticate required apps">
        <CodeGroup>
          ```bash Curl
          Copy and paste the OAuth URL into your web browser
          ```
          ```python Python
          import webbrowser

          # Handle OAuth authorization if needed
          if response.oauth_urls:
              for server_name, oauth_url in response.oauth_urls.items():
                  webbrowser.open(oauth_url)
                  input(f"Press Enter after completing {server_name} OAuth authorization...")
          ```

          ```typescript TypeScript
          // Handle OAuth authorization if needed
          if (response.oauthUrls) {
              for (const [serverName, oauthUrl] of Object.entries(response.oauthUrls)) {
                  if (typeof window !== 'undefined') {
                      window.open(oauthUrl);
                  }
                  console.log(`Please complete ${serverName} OAuth authorization at: ${oauthUrl}`);
                  // In a real application, you'd wait for OAuth completion via callback
                  await new Promise(resolve => {
                      console.log(`Press any key after completing ${serverName} OAuth authorization...`);
                      // This would be replaced with proper OAuth flow handling
                      resolve(null);
                  });
              }
          }
          ```
        </CodeGroup>
        
        <Info>
        **Authentication Methods**:
        - **API Key**: See [API Key authentication guide](/auth/api-key) for details.
        - **OAuth**: See [OAuth authentication guide](/auth/oauth) for details.
        </Info>
        
        <Check>
        🎉 **Your MCP Server URL is ready to use!** Once authentication is complete, you can use your MCP server URL with any MCP-compatible client.
        </Check>
      </Step>
      <Step title="(Optional) Connect to your AI application">
        <Tabs>
          <Tab title="LangChain">
            <CodeGroup>
              ```
/* Detailed source-code truncated for AI context efficiency. */
```
            </CodeGroup>
          </Tab>
          <Tab title="LlamaIndex">
           <CodeGroup>
              ```
/* Detailed source-code truncated for AI context efficiency. */
```
            </CodeGroup>
          </Tab>
          <Tab title="CrewAI">
            <Info>Coming soon</Info>
          </Tab>
          <Tab title="AutoGen">
            <CodeGroup>
                ```
/* Detailed source-code truncated for AI context efficiency. */
```
            </CodeGroup>
          </Tab>
        </Tabs>
      </Step>
    </Steps>
  </Tab>
  <Tab title="Open Source">
    <Tip>
    Visit https://github.com/Klavis-AI/klavis to view the source code and find more information
    </Tip>
    <Steps>
      <Step title="Install Strata MCP">
        <CodeGroup>
          ```bash pipx
          pipx install strata-mcp
          ```
          ```bash pip
          pip install strata-mcp
          ```
        </CodeGroup>
      </Step>
      <Step title="Add your MCP servers">
        Configure your MCP servers using the CLI tool.
        <CodeGroup>
          ```bash Add Server
          strata add
          ```
          ```bash List Servers
          strata list
          ```
          ```bash Enable Server
          strata enable <server-name>
          ```
        </CodeGroup>
      </Step>
      <Step title="Run Strata MCP Server">
        Start the Strata server to manage all your tools.
        <CodeGroup>
          ```bash Stdio Mode (Default)
          strata
          ```
          ```bash HTTP/SSE Mode
          strata run --port 8080
          ```
        </CodeGroup>
      </Step>
      <Step title="Connect to your AI application">
        Use the Strata tool to add your AI client.
        <CodeGroup>
          ```bash Claude Code
          strata tool add claude
          ```
          ```bash Cursor
          strata tool add cursor
          ```
          ```bash VSCode
          strata tool add vscode
          ```
        </CodeGroup>
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  If you're interested in 1:1 mapping between API and tool using our MCP Server Instance, [check here](/legacy/instance).
</Info>

## Next steps

<CardGroup cols={2}>
  <Card title="AI Platform Integrations" icon="handshake" href="/ai-platform-integration/overview">
    Integrate Klavis MCP Servers with leading AI platforms
  </Card>
  <Card title="Integrations" icon="server" href="/mcp-server/github">
    Explore available MCP servers
  </Card>
  <Card title="Strata" icon="layer-group" href="/concepts/strata">
    Progressive tool discovery across apps
  </Card>
  <Card title="API Reference" icon="magnifying-glass" href="/api-reference/introduction">
    REST endpoints and schemas
  </Card>
</CardGroup>

---

### CONTRIBUTING

# Contributing to Klavis AI

Thank you for your interest in contributing to Klavis AI! This document outlines the process and conventions we use for contributions, pull requests, and commit messages.

## Contributor License Agreement (CLA)

Before we can accept your contributions, we require all contributors to sign our Contributor License Agreement (CLA). This is a one-time process.

[Contributor License Agreement](https://cla-assistant.io/Klavis-AI/klavis)

The CLA helps ensure that everyone who submits a contribution has the legal right to do so and agrees to the terms under which the contribution is accepted. Without this agreement, we cannot review or accept your contributions.

## Table of Contents

- [Contributor License Agreement (CLA)](#contributor-license-agreement-cla)
- [Code of Conduct](#code-of-conduct)
- [Getting Started](#getting-started)
- [Development Workflow](#development-workflow)
- [Commit Message Convention](#commit-message-convention)
- [Pull Request Process](#pull-request-process)
- [Code Style Guidelines](#code-style-guidelines)
- [Testing Guidelines](#testing-guidelines)
- [License](#license)

## Code of Conduct

We expect all contributors to follow our Code of Conduct. Please be respectful and inclusive in all interactions.

## Getting Started

1. Fork the repository
2. Clone your fork: `git clone https://github.com/yourusername/klavisAi.git`
3. Add the upstream remote: `git remote add upstream https://github.com/Klavis-AI/klavis.git`
4. Create a new branch for your feature or bug fix
5. Make your changes
6. Submit a pull request

## Development Workflow

### Monorepo Structure

The project is organized as a monorepo with multiple MCP servers and clients:

- `mcp_servers/` - Contains individual Model Context Protocol servers
- `mcp_clients/` - Contains clients that connect to MCP servers

When making changes, be mindful of the scope of your change and any potential impacts on other components.

### Building MCP Servers

If you're interested in contributing a new MCP server to the project, we have a comprehensive guide to help you get started:

**[📖 MCP Server Guide](MCP_SERVER_GUIDE.md)** - A complete guide covering:
- What MCP servers are and how they work
- How to design effective tools for AI agents
- Development best practices and testing requirements
- Step-by-step instructions with examples

This guide is essential reading for anyone wanting to build high-quality MCP servers that integrate well with AI applications.

## Commit Message Convention

We follow a simplified version of the [Conventional Commits](https://www.conventionalcommits.org/) specification for commit messages.

Format:

```
<type>(<scope>): <subject>
```

### Type

Must be one of the following:

- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect the meaning of the code (formatting, etc.)
- `refactor`: A code change that neither fixes a bug nor adds a feature
- `perf`: A code change that improves performance
- `test`: Adding missing or correcting existing tests
- `chore`: Changes to the build process or auxiliary tools
- `ci`: Changes to CI configuration files and scripts

### Scope

The scope is optional and can be anything specifying the place of the commit change. For example: `slack`, `github`, `supabase`, etc.

### Subject

The subject contains a succinct description of the change:
- Use the imperative, present tense: "change" not "changed" nor "changes"
- Don't capitalize the first letter
- No period (.) at the end

### Examples

```
feat(slack): add user profile lookup functionality
```

```
fix(github): resolve PR comment retrieval issue
```

```
docs(core): update installation instructions
```

```
refactor(supabase): simplify authentication flow
```

## Pull Request Process

1. **Create a descriptive PR title** following the commit message format:
   ```
   <type>(<scope>): <subject>
   ```

2. **Fill in the PR template** with:
   - A clear description of the changes
   - The motivation for the changes
   - Any additional context that might be helpful
   - Screenshots if applicable

3. **Link related issues** using GitHub keywords like "Closes #123" or "Fixes #456"

4. **Keep PRs focused and reasonably sized** - Split large changes into smaller, more manageable PRs when possible

5. **Update documentation** if your changes affect the public API or user experience

6. **Add tests** for new features or bug fixes

7. **Make sure all tests pass** and code style checks complete successfully

8. **Request reviews** from appropriate team members

9. **Address review feedback** promptly and thoroughly

10. **Rebase your branch** on the latest main branch before merging


## Testing Guidelines

- Write tests for all new features and bug fixes
- Maintain or improve code coverage
- Test across multiple Node.js/Python/go versions when appropriate

## License

By contributing to Klavis AI, you agree that your contributions will be licensed under the project's [Apache 2.0 license](LICENSE).

---