# How to Integrate Kaneo with Other Services: MCP SDK, GitHub Plugin, and API Guide

> Integrate Kaneo seamlessly with other services using the MCP SDK, GitHub plugin, and API. Automate workflows, sync data, and trigger actions via TypeScript clients, webhooks, or CLI tools. Learn how.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-08

---

**Kaneo exposes a modular integration architecture through its MCP (Model Context Protocol) SDK, GitHub plugin system, and typed OpenAPI endpoints, enabling external services to automate workflows, sync data, and trigger actions via TypeScript clients, webhooks, or CLI tools.**

The `usekaneo/kaneo` repository is structured as a modular monorepo that cleanly separates the backend API (built with Hono and Drizzle ORM) from the frontend React application. This architecture makes it straightforward to integrate Kaneo with other services using well-defined entry points including a dedicated MCP SDK, a GitHub integration plugin, and configurable email services.

## Core Integration Points

### GitHub Integration Plugin

The **GitHub integration** provides webhooks, OAuth app installation flows, and bidirectional sync for issues, pull requests, and labels. Located in `apps/api/src/plugins/github/`, the system uses [`webhook-handler.ts`](https://github.com/usekaneo/kaneo/blob/main/webhook-handler.ts) to process incoming GitHub events and [`utils/github-app.ts`](https://github.com/usekaneo/kaneo/blob/main/utils/github-app.ts) to manage Octokit client instances and authentication. This plugin demonstrates the standard pattern for adding third-party service integrations to Kaneo.

### MCP (Kaneo CLI) SDK

The **MCP SDK** offers programmatic access to Kaneo's entire API surface through a TypeScript client. Found in `packages/mcp/src/`, the [`client.ts`](https://github.com/usekaneo/kaneo/blob/main/client.ts) module exports a `KaneoClient` class that wraps API calls, while [`cli.ts`](https://github.com/usekaneo/kaneo/blob/main/cli.ts) provides a command-line interface for automation scripts. External systems can import `@kaneo/mcp` to create tasks, manage projects, or sync data without writing raw HTTP requests.

### Email Service Integration

For services needing to send notifications through Kaneo's infrastructure, the email package (`packages/email/src/`) exposes configurable SMTP clients and templates. The [`smtp-config.ts`](https://github.com/usekaneo/kaneo/blob/main/smtp-config.ts) file centralizes mail server settings, while ready-made templates handle workspace invitations and OTP verification. External scripts can import these modules to send authenticated mail via Kaneo's provider.

### Webhooks Core and Plugin Registration

The generic webhook system in [`apps/api/src/plugins/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/index.ts) registers integration plugins and routes incoming events. While currently implemented for GitHub, this architecture supports extending to GitLab, Bitbucket, or custom providers by following the same registration pattern used for the GitHub plugin.

## API Contracts and Type Safety

All integrations communicate over typed **OpenAPI endpoints** defined with `hono-openapi`. The schema definitions in [`apps/api/src/schemas.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/schemas.ts) (including `githubIntegrationSchema`) are automatically exposed at [`/openapi.json`](https://github.com/usekaneo/kaneo/blob/main//openapi.json), allowing external clients to generate strongly-typed SDKs in any language. **Valibot** schemas validate all inputs, ensuring runtime type safety between Kaneo and integrated services.

The [`packages/libs/src/api-url.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/libs/src/api-url.ts) helper centralizes the API base URL definition, ensuring both internal and external services point to the correct endpoint regardless of deployment environment.

## Step-by-Step Integration Workflow

To integrate a new external service with Kaneo, follow this four-step pattern established by the GitHub plugin:

1. **Register the plugin** – Create a new folder under `apps/api/src/plugins/` and expose its routes in [`apps/api/src/plugins/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/index.ts).

2. **Implement webhook handlers** – Use the `github-app` utility pattern to verify incoming signatures and obtain authenticated SDK instances (e.g., Octokit for GitHub).

3. **Create frontend fetchers** – On the web side, add fetchers under `apps/web/src/fetchers/<service>/` that call your new API routes, then wrap them with TanStack Query hooks.

4. **Enable MCP access** – External scripts can instantiate `new KaneoClient({ apiUrl })` from `@kaneo/mcp` to invoke your new endpoints programmatically.

## Practical Integration Examples

### Consuming the GitHub Integration API

The following fetcher demonstrates how the web app retrieves GitHub integration data using the typed API client:

```typescript
// apps/web/src/fetchers/github-integration/get-github-integration.ts
import { client } from "@/lib/api-client";

export async function getGithubIntegration(projectId: string) {
  const response = await client["github-integration"].project[projectId].$get();
  return response.data; // typed according to the OpenAPI spec
}

```

### React Query Hook Implementation

Frontend components consume these fetchers through TanStack Query for caching and state management:

```typescript
// apps/web/src/hooks/queries/github-integration/use-get-github-integration.ts
import { useQuery } from "@tanstack/react-query";
import { getGithubIntegration } from "@/fetchers/github-integration/get-github-integration";

export function useGithubIntegration(projectId: string) {
  return useQuery({
    queryKey: ["github-integration", projectId],
    queryFn: () => getGithubIntegration(projectId),
  });
}

```

### Creating GitHub Integrations Programmatically

To establish a new GitHub connection from the UI:

```typescript
// apps/web/src/fetchers/github-integration/create-github-integration.ts
import { client } from "@/lib/api-client";

export async function createGithubIntegration(projectId: string, payload: {
  installationId: number;
  settingsUrl: string;
}) {
  const response = await client["github-integration"]
    .project[projectId].$post(payload);
  return response.data;
}

```

### Automating Tasks via the MCP Client

External Node.js scripts can drive Kaneo without direct HTTP calls:

```typescript
// scripts/sync-tasks.ts
import { KaneoClient } from "@kaneo/mcp";

(async () => {
  const client = new KaneoClient({ apiUrl: process.env.KANEO_API_URL! });

  // Fetch a project, then create a task
  const project = await client.projects.get("proj_abc123");
  await client.tasks.create({
    projectId: project.id,
    title: "Sync from external system",
    description: "Automatically created by external script",
  });
})();

```

### Sending Email from External Services

Integrate with Kaneo's email infrastructure for consistent messaging:

```typescript
// external-service/email-invite.ts
import { sendWorkspaceInvitation } from "@kaneo/email";

await sendWorkspaceInvitation({
  to: "newuser@example.com",
  workspaceName: "Acme Engineering",
  invitationLink: "https://kaneo.example.com/invite/xyz",
});

```

## Summary

- **Plugin-first architecture** allows adding new services by creating folders in `apps/api/src/plugins/` without modifying core code.
- **MCP SDK** ([`packages/mcp/src/kaneo/client.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/kaneo/client.ts)) provides a TypeScript client and CLI for external automation.
- **GitHub integration** (`apps/api/src/plugins/github/`) demonstrates webhook handling, OAuth flows, and REST fetchers.
- **OpenAPI contracts** ([`apps/api/src/schemas.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/schemas.ts)) ensure type-safe communication across all integrations.
- **Email service** (`packages/email/src/`) offers SMTP configuration and templates for external notification systems.

## Frequently Asked Questions

### How do I authenticate external services with the Kaneo API?

External services authenticate using standard API keys or OAuth flows depending on the integration type. The MCP client accepts an `apiUrl` and authentication tokens via environment variables, while the GitHub plugin uses the [`github-app.ts`](https://github.com/usekaneo/kaneo/blob/main/github-app.ts) utility to validate webhook signatures and manage Octokit instances securely.

### Can I integrate Kaneo with services other than GitHub?

Yes. The plugin architecture in [`apps/api/src/plugins/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/index.ts) is generic and extensible. You can create new integration folders following the GitHub plugin pattern to support GitLab, Bitbucket, or custom internal tools, registering them in the central plugin index.

### What is the MCP SDK used for?

The **MCP (Model Context Protocol) SDK** provides a TypeScript client ([`packages/mcp/src/kaneo/client.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/kaneo/client.ts)) and command-line interface ([`packages/mcp/src/cli.ts`](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/cli.ts)) that allow external scripts, CI pipelines, and automation tools to interact with Kaneo's API programmatically without constructing raw HTTP requests.

### Where are the API schema definitions located?

All schema definitions, including `githubIntegrationSchema`, are centralized in [`apps/api/src/schemas.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/schemas.ts) using Valibot. These schemas generate the OpenAPI specification available at [`/openapi.json`](https://github.com/usekaneo/kaneo/blob/main//openapi.json), enabling strongly-typed client generation for any programming language.