klavis Documentation

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


<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>
    
    **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
    
    <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>
    
    
    **Authentication Methods**:
    - **API Key**: See [API Key authentication guide](/auth/api-key) for details.
    - **OAuth**: See [OAuth authentication guide](/auth/oauth) for details.
    
    
    <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>
          ```

</CodeGroup>
          </Tab>
          <Tab title="LlamaIndex">
           <CodeGroup>
              ```
/* Detailed source-code truncated for AI context efficiency. */

</CodeGroup>
      </Tab>
      <Tab title="CrewAI">
        Coming soon
      </Tab>
      <Tab title="AutoGen">
        <CodeGroup>
            ```

</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>


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


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

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

## Pull Request Process

1. **Create a descriptive PR title** following the commit message format:

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

---