Documentation · MCP server

A phone line for your apps and AI agents

konnos ships with a built-in MCP server: a single endpoint that lets other apps and AI tools call konnos mid-build — create a repository, push the code they just wrote, check its status, and open issues — all on your terms, inside your walls.

What it is

MCP, 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.

The tool calls

What an agent can ask for

A focused set of actions that cover the whole loop — from an empty idea to pushed code with issues to track.

create_repo

Spin up a new private repository — name, description, visibility — and get its clone URL back, ready to push to.

push_code

Import or push a set of files into a repository and branch, so an agent can ship the code it just generated.

repo_status

Read a repository's current state — default branch, latest commit, open issues — to decide what to do next.

open_issue

File an issue with a title and body — for a TODO, a bug an agent spotted, or a follow-up task to track.

Example call

Create a repo, then push into it

An agent calls create_repo and gets a clone URL back, then calls push_code to ship the files it generated.

// 1. create the repository
{
  "tool": "create_repo",
  "arguments": {
    "name": "invoice-parser",
    "description": "Parses PDF invoices into JSON",
    "private": true
  }
}

// -> { "clone_url": "https://code.konnos.org/<you>/invoice-parser.git",
//      "default_branch": "main" }

// 2. push the generated code
{
  "tool": "push_code",
  "arguments": {
    "repo": "<you>/invoice-parser",
    "branch": "main",
    "message": "Initial parser implementation",
    "files": [
      { "path": "README.md", "content": "# invoice-parser" },
      { "path": "src/index.ts", "content": "export function parse() {}" }
    ]
  }
}

How to connect

One endpoint, one token

Point your MCP-capable client at the konnos endpoint and authenticate with an access token (the same kind you mint for the REST API). Most clients take a small JSON config like this:

{
  "mcpServers": {
    "konnos": {
      "url": "https://code.konnos.org/mcp",
      "headers": {
        "Authorization": "token <YOUR_TOKEN>"
      }
    }
  }
}

The token carries your permissions, so an agent can only do what you can do. Grant narrowly, rotate freely, and revoke in one click whenever you want to hang up the line.

Wire konnos into your build

Mint a token, point your agent at the endpoint, and let it work — without your code ever leaving home.

Start freeBack to docs