Automation

The MCP phone line

konnos ships with a built-in MCP server: a single connection that lets other apps and AI tools call konnos mid-build — create a repo, push the files they generated, open issues, and more — all on your terms, inside your walls.

What MCP is, in plain terms

MCP — the Model Context Protocol — is a shared language that lets an app or an AI assistant call out to other tools while it works. Think of it as a phone line: your tool picks up, dials konnos, and asks it to do something concrete.

Instead of a human clicking around the website, your build pipeline or coding agent can say “make me a repo and push this code into it” — and konnos does it. Because it's your konnos, your code and context never leave for someone else's platform.

Configure it

The konnos MCP authenticates with a per-user access token and needs two environment variables:

  • KONNOS_URL — your konnos base URL, e.g. https://code.konnos.org.
  • KONNOS_TOKEN — a Personal Access Token (the same kind you use for git-over-HTTPS and the REST API).

Most MCP-capable clients take a small JSON config that runs the server and passes those through:

{
  "mcpServers": {
    "konnos": {
      "command": "npx",
      "args": ["-y", "@konnos/mcp"],
      "env": {
        "KONNOS_URL": "https://code.konnos.org",
        "KONNOS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

The token carries your permissions

An agent can only do what you can do. Grant narrowly, rotate freely, and revoke in one move whenever you want to hang up the line.

The tools an agent can call

A focused set that covers the whole loop — from an empty idea to pushed code with issues to track:

whoami

Confirm which konnos account the current token acts as.

list_repos

List the repositories the token owner can access.

get_repo

Fetch a single repository's info by owner and name.

konnos_create_repo

Create a new repository owned by the token owner (optionally seed a README).

put_file

Create or update a file in a repo, committing directly — how an agent ships the code it wrote.

list_commits

Read a repository's commit history, newest first — optionally scoped to a branch.

create_issue

Open an issue on a repository with a title and body.

list_issues

List a repo's issues, filtered by open / closed / all.

create_org

Create a new organization owned by the token owner.

create_webhook

Add a repo webhook that POSTs events to a URL you choose (defaults to push / JSON).

delete_repo

Permanently delete a repo — GATED: you must pass confirm equal to the exact owner/repo, or it refuses.

A short example

An agent creates a repository, then writes a file into it — two calls:

// 1. create the repository
{
  "tool": "konnos_create_repo",
  "arguments": { "name": "invoice-parser", "private": true, "auto_init": true }
}

// 2. commit a file into it
{
  "tool": "put_file",
  "arguments": {
    "owner": "<you>",
    "repo": "invoice-parser",
    "path": "src/index.ts",
    "content": "export function parse() {}",
    "message": "Add parser entrypoint"
  }
}

Prefer plain HTTPS? Everything the MCP does is also available on the REST API.