KnightLeap exposes a token-authenticated REST API and a hosted MCP server, so your AI coding agent — Claude Code, OpenAI Codex, Gemini CLI, a Claude.ai connector, or any MCP client — can read and update your workspace while you vibe-code. Pick up a story, mark it in progress, ship, send it to review — your sprint tracks itself. A token acts as you: it can do exactly what you can do in the app, and nothing more.
In the app, open your Profile and find the API & Claude access section. Create a token and give it a name you'll recognize later (e.g. “MacBook / Claude Code”). Don't have an account yet? Start free — 14 days free, no credit card.
KnightLeap speaks the open Model Context Protocol (MCP) over HTTP, so any MCP-capable agent connects with the same token — nothing to install.
Your token is a single environment variable, reused by every client and every project. Add it to your shell profile (e.g. ~/.zshrc) once — then point every client at ${KNIGHTLEAP_TOKEN}, never a hardcoded secret:
# in ~/.zshrc — set once, reused everywhere
export KNIGHTLEAP_TOKEN=kl_your_token_here
After adding it, open a fresh terminal (or restart your coding agent) so it picks up the variable.
Add a .mcp.json at the repo root. Claude Code expands ${KNIGHTLEAP_TOKEN} from your environment at load time, so the file carries no secret and is safe to commit:
// .mcp.json — at the repo root
{
"mcpServers": {
"knightleap": {
"type": "http",
"url": "https://knightleap.com/mcp",
"headers": { "Authorization": "Bearer ${KNIGHTLEAP_TOKEN}" }
}
}
}
The KnightLeap skill (below) writes this for you, and it’s where per-project scoping lives (next section). Prefer one global connection instead of a per-repo file? You can run claude mcp add knightleap --scope user with a literal --header "Authorization: Bearer kl_…" — but that bakes the token into Claude Code’s own config (~/.claude.json) and does not set the KNIGHTLEAP_TOKEN variable, so it won’t carry over to the scoped per-repo setup the rest of this guide uses.
Codex reads remote MCP servers from ~/.codex/config.toml, keeping the secret in an environment variable:
# ~/.codex/config.toml
[mcp_servers.knightleap]
url = "https://knightleap.com/mcp"
bearer_token_env_var = "KNIGHTLEAP_TOKEN"
Add KnightLeap to ~/.gemini/settings.json (global, all projects). The token is read from an environment variable too:
// ~/.gemini/settings.json
{
"mcpServers": {
"knightleap": {
"httpUrl": "https://knightleap.com/mcp",
"headers": { "Authorization": "Bearer ${KNIGHTLEAP_TOKEN}" }
}
}
}
Working inside one project's repo? Add ?project=KEY to the URL (your project's key, e.g. VID) and the agent defaults to that project — so you never have to tell it which project you mean. Token and scope are independent: the token is unchanged, and an explicit project on any tool call still overrides the default.
Just add ?project=VID to the URL in your .mcp.json (or in your global Codex / Gemini config for one default everywhere). The token is unchanged — only the URL gains a query string:
// .mcp.json — scoped to one project, no secret in it
{
"mcpServers": {
"knightleap": {
"type": "http",
"url": "https://knightleap.com/mcp?project=VID",
"headers": { "Authorization": "Bearer ${KNIGHTLEAP_TOKEN}" }
}
}
}
Prefer to skip the config? Install the KnightLeap skill for Claude Code once, then run /knightleap setup project <name> in any repo — it writes the scoped .mcp.json for you and bundles the sprint workflow.
# install once
mkdir -p ~/.claude/skills/knightleap && \
curl -fsSL https://knightleap.com/skill/knightleap/SKILL.md -o ~/.claude/skills/knightleap/SKILL.md
Tools alone won't make an agent track your work — give it the workflow. Paste this into your agent's instructions file — CLAUDE.md for Claude Code, AGENTS.md for Codex, or GEMINI.md for Gemini CLI (or your global agent instructions):
## KnightLeap
When you start development work, call list_my_stories to find the matching
KnightLeap story (or create_story under the right project/epic if none exists),
then start_story it — that pulls it into the current week's sprint.
As you work, tick off the checklist with check_task. If you get blocked,
set_status to stuck; if a review bounces back, set_status to review_failed and pick it up again.
When the work is done and verified, call complete_story to send it for review.
After a sprint that moved a metric, record it: check_in_key_result with the new
value, and check_in_objective with this week's confidence (1–10) and a short note.
Now you can just say “start the onboarding story and work on it” and the agent will move it through your sprint as it goes.
The MCP server exposes thirty-four tools:
| Tool | What it does |
|---|---|
whoami | Who you are and which project this connection is scoped to — your name, the project's name + key, its Jira-style key format, and the current sprint key. Call it first to learn the exact keys to use instead of copying a prefix from an example |
list_my_stories | Your assigned and unclaimed one-off stories, filterable by status or project (routine occurrences are excluded; each story carries a kind of story or routine) |
get_story | One story in full: description, checklist, status, people |
start_story | Mark a story in progress |
complete_story | Send a story to review (notifies the reviewer) |
set_status | Set a story to any status (e.g. stuck, review_failed, back to backlog) |
create_story | Add a new backlog story to a project, optionally under an epic |
update_story | Edit a story in place — name, description, estimated hours — to rescope it without losing its key, checklist, or history (planning rights) |
schedule_story | Move a backlog story into the current sprint — onto a named goal, or ungrouped (no goal) by default |
unschedule_story | Return a scheduled story to the backlog |
assign_goal | Re-file a story under a sprint goal (or clear it) without changing status — housekeeping for stories already in a sprint, including completed ones |
delete_story | Permanently delete a story and its checklist (planning rights) |
check_task | Complete a checklist item |
add_task | Add a checklist item to a story |
update_task | Rename a checklist item |
delete_task | Remove a checklist item from a story |
add_acceptance_criterion | Add an acceptance criterion (a definition-of-done check) to a story |
check_acceptance_criterion | Mark an acceptance criterion done (or undone) |
update_acceptance_criterion | Rephrase an acceptance criterion |
delete_acceptance_criterion | Remove an acceptance criterion from a story |
list_epics | Epics (large bodies of work) in your projects |
create_epic | Create an epic to group related stories under |
delete_epic | Delete an epic; its stories and goals are unlinked, not deleted (planning rights) |
sprint_summary | This week across your projects: goals, hours, capacity |
sprint_stories | This week's sprint backlog: stories grouped by goal (with an Ungrouped bucket for goal-less stories), with status and hours |
create_sprint_goal | Add a goal (a sub-bucket) to a sprint, optionally aligned to an objective (max 3 per sprint; planning rights) |
activate_sprint | Start a planned sprint (planning → active) so it becomes the current sprint and burns down — needs at least one goal (planning rights) |
set_sprint_capacity | Plan a sprint's committed hours for the week (clears any skip); planning rights |
skip_sprint / unskip_sprint | Mark a project's week as skipped, or un-skip it (planning rights) |
set_member_capacity | Set a teammate's available hours for a week; owners set anyone's, others their own |
get_sprint_review | Read a sprint's review/retro (the six fields + completion score) |
write_sprint_review | Write/update a sprint's review; optionally complete the sprint (active → reviewing → completed); planning rights |
list_objectives | The current quarter's OKRs with key-result progress |
create_objective | Create a quarterly objective and its key results under a project or portfolio |
update_objective | Edit an objective's title or description |
delete_objective | Delete an objective with its key results and check-ins (manage-business rights) |
add_key_result | Add a key result to an objective |
update_key_result | Edit a key result's title, unit, start, or target |
delete_key_result | Remove a key result from its objective |
check_in_key_result | Record this week's value, moving the key result's headline number |
check_in_objective | Record this week's confidence (1–10) and a note on an objective |
link_routine_to_key_result | Auto-feed a key result from a routine — completed occurrences move the KR value (weekly or cumulative count); manual check-ins win (planning rights) |
unlink_routine_from_key_result | Stop a routine feeding a key result; past auto-fed check-ins remain as history (planning rights) |
Prefer scripts or curl? Every tool above maps to a JSON endpoint under /api/v1. Send your token as a Bearer header:
# your stories that are in progress
curl -s https://knightleap.com/api/v1/stories?status=in_progress \
-H "Authorization: Bearer kl_your_token_here"
# send a story to review (address it by its project-key id)
curl -s -X PATCH https://knightleap.com/api/v1/stories/KDP-13 \
-H "Authorization: Bearer kl_your_token_here" \
-H "Content-Type: application/json" \
-d '{"story":{"status":"ready_for_review"}}'
Available routes: GET/POST /api/v1/stories, GET/PATCH/DELETE /api/v1/stories/:id, POST /api/v1/stories/:id/schedule, POST /api/v1/stories/:id/assign_goal, POST /api/v1/stories/:id/link_key_result, POST /api/v1/stories/:id/unlink_key_result, POST /api/v1/tasks, PATCH/DELETE /api/v1/tasks/:id, GET /api/v1/sprints/current, POST /api/v1/sprints/:sprint_id/activate, POST /api/v1/sprints/:sprint_id/capacity, POST /api/v1/sprints/:sprint_id/skip, POST /api/v1/sprints/:sprint_id/unskip, GET/PUT /api/v1/sprints/:sprint_id/review, POST /api/v1/capacities, POST /api/v1/sprints/:sprint_id/goals, GET/POST /api/v1/objectives, PATCH/DELETE /api/v1/objectives/:id, POST /api/v1/objectives/:id/check_in, POST /api/v1/key_results, PATCH/DELETE /api/v1/key_results/:id, POST /api/v1/key_results/:id/check_in.