Skip to content
Upjack

Quick Start

This guide walks you through creating your first Upjack app from scratch. By the end, you will have a working application with entity management, validation, and search — all from a JSON Schema and a manifest file.

1. Install and scaffold

Section titled “1. Install and scaffold”

Install Upjack and scaffold a new app:

Terminal window
uv add upjack    # or: pip install upjack
upjack init
# prompts: App name? → my-crm | First entity? → contact

This creates a ready-to-run app directory:

my-crm/
  manifest.json               # Wiring: entities, skills, hooks, schedules
  schemas/
    contact.schema.json        # What a contact looks like (JSON Schema)
  context.md                   # Domain knowledge the agent always has
  seed/
    sample-contacts.json       # Initial data
  server.py                    # 3-line MCP server entry point

You can also scaffold manually by creating the files yourself. The next two steps show you how.

2. Create a manifest

Section titled “2. Create a manifest”

manifest.json follows the MCPB package format. The upjack-specific configuration lives inside _meta["ai.nimblebrain/upjack"], which MCPB treats as opaque vendor metadata. Non-MCPB-aware tools can install an Upjack app as a regular MCP server and ignore the extension entirely.

{
  "manifest_version": "0.4",
  "name": "my-notes-app",
  "version": "0.1.0",
  "title": "Notes",
  "server": null,
  "_meta": {
    "ai.nimblebrain/upjack": {
      "upjack_version": "0.1",
      "namespace": "apps/notes",
      "entities": [
        {
          "name": "note",
          "plural": "notes",
          "prefix": "nt",
          "schema": "schemas/note.schema.json"
        }
      ]
    }
  }
}

The namespace (apps/notes) determines where entity files are stored on disk. The prefix (nt) is prepended to generated IDs, so you can identify entity types at a glance — for example, nt_01HZ3QKB... is a note.

3. Create an entity schema

Section titled “3. Create an entity schema”

Create schemas/note.schema.json. This is a standard JSON Schema (draft 2020-12) describing the shape of a note:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "body": { "type": "string" },
    "tags": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["title"]
}

The schema defines what fields a note can have and which are required. Upjack validates every write against this schema, so invalid data never reaches storage.

4. Use it in Python

Section titled “4. Use it in Python”

With the manifest and schema in place, you can start managing entities immediately:

from upjack import UpjackApp


app = UpjackApp.from_manifest("manifest.json")


# Create an entity
note = app.create_entity("note", {"title": "Hello", "body": "My first note"})
print(note["id"])    # nt_01HZ3QKB9YWVJ0RPFA7MT8C5X
print(note["type"])  # note


# List entities
notes = app.list_entities("note")


# Search
results = app.search_entities("note", query="hello")


# Update
app.update_entity("note", note["id"], {"body": "Updated body"})


# Delete (soft delete by default)
app.delete_entity("note", note["id"])

What happened: The library created a JSON file at ./apps/notes/data/notes/nt_01HZ3QKB....json containing your note with an auto-generated ID, timestamps, and the data you provided. The path comes from the namespace and plural fields in your manifest.

Soft-deleting sets status to "deleted" but keeps the file on disk. Pass hard=True to remove it permanently.

5. (Optional) Serve as an MCP server

Section titled “5. (Optional) Serve as an MCP server”

To expose your app as an MCP server that AI agents can connect to, install with MCP support:

Terminal window
uv add "upjack[mcp]"

Then create a server with a single function call:

from upjack.server import create_server


mcp = create_server("manifest.json")
mcp.run()
# Exposes: create_note, get_note, update_note, list_notes, search_notes, delete_note

The server automatically generates six tools for each entity defined in your manifest, plus resources for your context and skills.

6. Connect to your agent

Section titled “6. Connect to your agent”

Upjack apps are MCPB bundles. Use mpak to run them with any MCP-compatible client.

First, install mpak if you have not already:

Terminal window
npm install -g @nicepkg/mpak

Then connect your published bundle (or a local .mcpb file) to your agent:

Claude Code

Terminal window
claude mcp add my-notes-app -- mpak run @yourorg/my-notes-app

Claude Desktop / Cursor / Windsurf — add to your MCP config file (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "my-notes-app": {
      "command": "mpak",
      "args": ["run", "@yourorg/my-notes-app"]
    }
  }
}

Local development — run a local bundle without publishing:

Terminal window
mpak run --local ./my-notes-app.mcpb

The agent will see tools like create_note, list_notes, and search_notes, along with resources like upjack://context (your domain knowledge) and upjack://skills/* (your skill documents).

Next Steps

Section titled “Next Steps”