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

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 to process incoming GitHub events and 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 module exports a KaneoClient class that wraps API calls, while 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 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 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 (including githubIntegrationSchema) are automatically exposed at /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 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.

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:

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

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

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

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

// 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) 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) 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 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 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) and command-line interface (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 using Valibot. These schemas generate the OpenAPI specification available at /openapi.json, enabling strongly-typed client generation for any programming language.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}