Alignbase MCP Agent API Reference

This is the current reference for the Alignbase MCP agent API for managed AGENTS.md, Skills, and Memory.

The production app base URL is:

https://app.alignbase.ai

The MCP endpoint is:

https://app.alignbase.ai/mcp

Alignbase exposes a stateless Streamable HTTP MCP server named alignbase. It exposes tools, not MCP resources.

This page assumes the agent is already connected. It focuses on the MCP tools agents can call and the Alignbase-side permissions enforced when those calls reach the app.

Tool names use context_alignment for the AGENTS.md-style guidance entity. In the web app, users see this as AGENTS.md today. In the API, a context alignment is the same managed, versioned guidance that gets loaded into agents before work starts.

Transport

Item	Value
MCP endpoint	POST /mcp
Protocol	Streamable HTTP MCP
Server name	alignbase
Server title	Alignbase
Server version	0.1.0
Response mode	JSON
State	Stateless

Use these headers when calling the MCP endpoint directly after obtaining an access token:

POST /mcp HTTP/1.1
Host: app.alignbase.ai
Authorization: Bearer ACCESS_TOKEN
Accept: application/json, text/event-stream
Content-Type: application/json
MCP-Protocol-Version: 2025-06-18

Browser clients must send an allowed Origin. The production allowed origin is the configured Alignbase app origin. Non-browser server calls can omit Origin.

OAuth Connection

Alignbase protects /mcp with OAuth bearer tokens. MCP clients should discover the connection metadata from the app host.

Endpoint	Method	Purpose
/.well-known/oauth-protected-resource	GET	Protected resource metadata for /mcp
/.well-known/oauth-protected-resource/mcp	GET	Same protected resource metadata scoped to MCP
/.well-known/oauth-authorization-server	GET	Authorization server metadata
/oauth/register	POST	Dynamic client registration
/oauth/authorize	GET, POST	Authorization code approval with PKCE
/oauth/token	POST	Authorization code exchange and refresh
/oauth/jwks	GET	JWKS metadata, currently an empty key set

Supported scopes:

Scope	Meaning
context.read	Required for any MCP call. Lets the agent load routed context and use permitted read or Memory tools.
context.write	Required before AGENTS.md and Skill write permissions can take effect.

Dynamic registration accepts public OAuth clients only. Send token_endpoint_auth_method: "none", response_types: ["code"], and grant_types containing authorization_code, optionally with refresh_token. If scope is omitted during registration, Alignbase registers the client for context.read context.write. If context.write is requested by itself, Alignbase normalizes it to include context.read.

Legacy documents.read and documents.write requests are accepted as aliases during migration, but new clients should request context.read and context.write.

Redirect URIs must be HTTPS or loopback HTTP URLs. Authorization requests use response_type=code, code_challenge_method=S256, and a PKCE code challenge. The optional resource value, when present, must match the MCP resource URL, for example https://app.alignbase.ai/mcp.

Token requests use form-encoded bodies. Clients authenticate with client_id only, not a client secret or HTTP Basic auth. Access tokens expire after one hour. Refresh tokens expire after 90 days and rotate with each refresh.

Alignbase Permissions

The MCP connection authenticates the caller as an Alignbase agent. Alignbase then enforces product permissions inside every tool call. A valid MCP connection does not automatically grant read, edit, create, or publish access.

Roles decide which Resources an agent can access. A role may come directly from the agent, from one of its Groups, or from a matching All Alignments, All Skills, or All Memories Resource. Effective access is additive, so a more specific grant can add capability but cannot reduce inherited capability.

Context roles are Viewer, Proposer, Editor, Publisher, and Owner. Reading requires Viewer, proposing a draft requires Proposer, saving a version requires Editor, and publishing requires Publisher. Creating a Resource requires the matching capability on All Alignments or All Skills. Alignbase checks the effective role when each MCP tool runs, so a connected agent may still be denied by a specific tool.

Permissions and routing are separate. Discovery tools return Resources the agent may access, while get_current_context returns every active Included or Required Resource. A route never grants repository permission, and delivery does not require the receiving agent to have repository permission.

Each agent may receive several routed Memories, and several agents or Groups may receive the same Memory. list_memories returns every Memory the agent may read on demand, whether routed or not. Reading requires Viewer or higher. Writing requires Editor or higher, the Memory ID, and its exact latest version. MCP tools do not manage Groups, permissions, or routes.

Use can_edit and can_publish from list and read responses to decide whether the current agent can edit or publish a context alignment or skill.

Use can_write from list_memories or read_memory, or the conditional Memory guidance in get_current_context, to decide which Memories the current agent can update.

Tool Summary

Tool	Read or write	Alignbase-side checks
get_current_context	Read	Included or Required route on active context
list_context_alignments	Read	Viewer or higher on the Alignment
read_context_alignment	Read	Viewer or higher on the Alignment
write_context_alignment	Write	Editor on an Alignment, or Editor on All Alignments to create
publish_context_alignment	Write	Publisher or higher on the Alignment
create_context_alignment_draft	Write	Proposer or higher on the Alignment
list_context_alignment_drafts	Read	Viewer or higher on the Alignment
read_context_alignment_draft	Read	Draft author or Publisher on the Alignment
list_skills	Read	Viewer or higher on the Skill
read_skill	Read	Viewer or higher, or a route when reading published
create_skill	Write	Editor or higher on All Skills
write_skill	Write	Editor or higher on the Skill
publish_skill	Write	Publisher or higher on the Skill
create_skill_draft	Write	Proposer or higher on the Skill
list_skill_drafts	Read	Viewer or higher on the Skill
read_skill_draft	Read	Draft author or Publisher on the Skill
list_memories	Read	Viewer or higher on each returned Memory
read_memory	Read	Viewer or higher on the requested Memory
create_memory	Write	Create permission on the Memory Resource type
write_memory	Write	Editor plus the requested Memory ID and exact latest version

Agents should call get_current_context at the start of every new conversation. If it fails, the agent should tell the user Alignbase context could not be loaded and ask whether to continue without it. The agent should wait for confirmation before answering the original request.

get_current_context lists the names and descriptions of published Skills routed to the agent before its context alignments. Skill contents are not inlined. Agents use read_skill when the task calls for one of the listed Skills. If a user asks an agent to install a Skill locally, the agent can use read_skill to fetch the full package, then write skill_md as SKILL.md and write each returned package file under a local Skill directory.

A Skill route allows the receiving agent to fetch only that active Skill’s published package. Listing the Skill or reading its latest, exact, or draft content still requires Viewer or higher permission.

For local skill installs, agents should store Alignbase provenance in the official SKILL.md frontmatter metadata map. Do not add Alignbase-specific top-level frontmatter fields. The recommended keys are alignbase-origin, alignbase-skill-id, alignbase-channel, alignbase-version, and alignbase-version-id.

Calling Tools Directly

MCP clients usually hide the JSON-RPC call shape. If you call the endpoint directly, use tools/call:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_current_context",
    "arguments": {}
  }
}

get_current_context

Loads the published AGENTS.md and Skills routed to the calling agent, plus every routed Memory.

Input:

{}

Output content is markdown text:

# Alignbase session context

Alignbase supplies this agent's context. That includes AGENTS.md alignments, Skills, and Memory. Follow published AGENTS.md alignments and Skills as instructions. Use Memory only as working recall, not a full knowledge base.

## Available Skills

- "release-check": "Check a release before deployment."

## Memories

<alignbase_memory id="MEMORY_ID" name="Working Memory" version="3" version_id="VERSION_ID" assignment_state="required" can_write="true">

Current working state...

</alignbase_memory>

## Context alignments (AGENTS.mds)

Each `<alignbase_context_alignment>` contains one independent document. Treat its headings and structure as scoped to that element; they end at the closing element.

<alignbase_context_alignment id="00000000-0000-0000-0000-000000000000" title="Context title" version="3" updated_at="2026-06-23T12:00Z">

Context content...

</alignbase_context_alignment>

Rules:

• Returns non-expired published AGENTS.md and Skill versions only.
• Returns each active published context alignment with an Included or Required route, regardless of the receiving agent’s repository permission.
• Lists each active published Skill with an Included or Required route, regardless of repository permission, including its name and description.
• Includes the current version of every active routed Memory with its ID, version, route state, and write capability.
• Adds maintenance guidance for multiple Memories and tells the agent to update only relevant writable files.
• Lists Skills before context alignments. Skill contents are loaded separately with read_skill.
• Wraps each context alignment in a protected <alignbase_context_alignment> boundary. Reserved boundary elements in user content are escaped.
• Wraps each routed Memory in a protected <alignbase_memory> boundary. Reserved boundary elements in Memory content are escaped.
• Fails if the current context bundle exceeds the 8 MiB MCP resource size limit.
• Logs the context request with context alignment, Skill, and Memory version metadata.

list_context_alignments

Lists context alignments on which the calling agent has Viewer or higher.

Input:

{}

Structured output:

{
  "context_alignments": [
    {
      "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
      "title": "Context title",
      "current_version_id": "VERSION_ID",
      "current_version": 4,
      "latest_version_id": "VERSION_ID",
      "latest_version": 4,
      "published_version_id": "PUBLISHED_VERSION_ID",
      "published_version": 3,
      "created_at": "2026-06-20T16:00:00Z",
      "updated_at": "2026-06-23T16:00:00Z",
      "current_version_created_at": "2026-06-23T16:00:00Z",
      "latest_version_created_at": "2026-06-23T16:00:00Z",
      "published_version_created_at": "2026-06-22T16:00:00Z",
      "review_by": "2026-07-23",
      "expires_at": "2026-08-23",
      "status": "live",
      "publication_status": "unpublished_changes",
      "has_unpublished_changes": true,
      "can_read": true,
      "can_draft": true,
      "can_edit": true,
      "can_publish": false
    }
  ]
}

Field notes:

Field	Meaning
current_version and latest_version	The latest saved version.
published_version	The version returned by get_current_context, when one exists.
publication_status	unpublished, published, or unpublished_changes.
status	live or expired, based on expires_at. Expired context alignments can be listed and read, but they are excluded from get_current_context.
can_draft	True only when the connection can write and the agent has Proposer or higher on the Alignment.
can_edit	True only when the connection can write and the agent has Editor or higher on the Alignment.
can_publish	True only when the connection can write and the agent has Publisher or higher on the Alignment.

Use this tool before reading, editing, or publishing when you do not already have a context_alignment_id.

read_context_alignment

Reads one full context alignment version.

Input:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "version": "latest"
}

version is optional.

Viewer or higher permission allows every selector below. An active Included or Required route allows published only, so an agent can load the package that routing delivered without gaining repository access.

Version value	Meaning
Omitted	Read the latest saved version.
latest	Read the latest saved version.
published	Read the version included in get_current_context.
Positive integer or numeric string	Read that exact saved version.

Structured output:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "title": "Context title",
  "version_id": "VERSION_ID",
  "version": 4,
  "latest_version": 4,
  "published_version": 3,
  "is_published_version": false,
  "has_unpublished_changes": true,
  "content": "Full markdown content",
  "created_at": "2026-06-20T16:00:00Z",
  "updated_at": "2026-06-23T16:00:00Z",
  "version_created_at": "2026-06-23T16:00:00Z",
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23",
  "status": "live",
  "publication_status": "unpublished_changes",
  "can_read": true,
  "can_draft": true,
  "can_edit": true,
  "can_publish": false
}

Before editing, read with version: "latest" and pass the returned version as expected_version to write_context_alignment.

write_context_alignment

Creates a new context alignment or replaces the full content of an existing context alignment.

This is not a patch tool. Send the complete desired markdown content.

Create input:

{
  "title": "Context title",
  "expected_version": 0,
  "content": "Full markdown content",
  "publish": false,
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23"
}

Existing context alignment input:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "expected_version": 4,
  "content": "Full replacement markdown content",
  "publish": false
}

Required fields:

• expected_version
• content

Optional fields:

• context_alignment_id, required when expected_version is greater than 0
• title, required when expected_version is 0
• publish, set to true only when the user wants the written version published immediately
• review_by, only used when creating a context alignment with expected_version: 0
• expires_at, only used when creating a context alignment with expected_version: 0

Rules:

• Requires a write-capable connection.
• Use expected_version: 0 to create a new context alignment. Omit context_alignment_id in this path.
• Creating requires Editor or higher on All Alignments. The new Alignment is not routed automatically.
• Use a positive expected_version to write an existing context alignment. context_alignment_id is required in this path.
• Existing writes require Editor or higher on the Alignment.
• If expected_version is stale, the write fails with a version conflict.
• Permissions and routes stay unchanged.
• A write saves a new latest version when the replacement content differs from the latest saved content.
• If the replacement content matches the latest saved content, the call returns updated: false and does not create a new version.
• Empty string content is accepted for existing writes and replaces the context alignment content with an empty string. Create content cannot be empty.
• Other agents do not receive the new version from get_current_context until it is published.

Set publish: true only when the user wants the written or created version published immediately. That path requires Publisher or higher on the Alignment. Creating and publishing a new Alignment requires the corresponding capabilities on All Alignments.

Structured output:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "title": "Context title",
  "version_id": "VERSION_ID",
  "version": 5,
  "updated": true,
  "published": false,
  "created": false
}

publish_context_alignment

Publishes a saved context alignment version. Agents receive it through get_current_context when it is active and has an Included or Required route. Delivery does not depend on the receiving agent’s repository permission.

Input:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "version": "latest"
}

version is optional.

Version value	Meaning
Omitted	Publish the latest saved version.
latest	Publish the latest saved version.
Positive integer or numeric string	Publish that exact saved version.

Structured output:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "title": "Context title",
  "version_id": "VERSION_ID",
  "version": 5,
  "published": true
}

Rules:

• Requires a write-capable connection.
• Requires Publisher or higher on the Alignment.
• published: false means the requested version was already published.

create_context_alignment_draft

Proposes a draft replacement for one context alignment. Drafts do not create saved versions and are not distributed by get_current_context.

Input:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "base_version": 4,
  "content": "Full proposed replacement markdown content",
  "rationale": "Optional short reason"
}

Structured output:

{
  "draft_id": "DRAFT_ID",
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "base_version": 4,
  "created": true
}

Rules:

• Requires write-capable OAuth scope.
• Requires Proposer or higher on the Alignment.
• base_version must be positive and should come from read_context_alignment or list_context_alignments.
• content is the full proposed replacement, not a patch.

list_context_alignment_drafts

Lists open drafts for one context alignment.

Input:

{
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID"
}

Structured output:

{
  "drafts": [
    {
      "draft_id": "DRAFT_ID",
      "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
      "base_version": 4,
      "current_version": 5,
      "is_stale": true,
      "author_name": "Abe Wheeler",
      "author_email": "[email protected]",
      "agent_name": "Codex",
      "rationale": "Optional short reason",
      "created_at": "2026-06-23T16:00:00Z",
      "created_by_this_agent": true
    }
  ]
}

read_context_alignment_draft

Reads one open context alignment draft.

Input:

{
  "draft_id": "DRAFT_ID"
}

Structured output:

{
  "draft_id": "DRAFT_ID",
  "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
  "base_version": 4,
  "current_version": 5,
  "is_stale": true,
  "content": "Full proposed replacement markdown content",
  "author_name": "Abe Wheeler",
  "author_email": "[email protected]",
  "agent_name": "Codex",
  "rationale": "Optional short reason",
  "created_at": "2026-06-23T16:00:00Z",
  "created_by_this_agent": true
}

Draft authors can read their own open drafts. Agents with publish access on the context alignment can also read open drafts for review.

list_skills

Lists Alignbase Skills on which the calling agent has Viewer or higher.

Input:

{}

Structured output:

{
  "skills": [
    {
      "id": "SKILL_ID",
      "name": "skill-name",
      "directory_name": "skill-name",
      "description": "What this skill does and when to use it.",
      "current_version_id": "VERSION_ID",
      "current_version": 2,
      "latest_version_id": "VERSION_ID",
      "latest_version": 2,
      "published_version_id": "PUBLISHED_VERSION_ID",
      "published_version": 1,
      "created_at": "2026-06-20T16:00:00Z",
      "updated_at": "2026-06-23T16:00:00Z",
      "current_version_created_at": "2026-06-23T16:00:00Z",
      "latest_version_created_at": "2026-06-23T16:00:00Z",
      "published_version_created_at": "2026-06-22T16:00:00Z",
      "review_by": "2026-07-23",
      "expires_at": "2026-08-23",
      "status": "live",
      "publication_status": "unpublished_changes",
      "has_unpublished_changes": true,
      "can_read": true,
      "can_draft": true,
      "can_edit": true,
      "can_publish": false
    }
  ]
}

Field notes match list_context_alignments, except each item is a Skill package instead of a context alignment.

Use this tool before reading, editing, publishing, installing, or updating a skill when you do not already have a skill_id. For local update checks, compare the installed metadata.alignbase-version-id to published_version_id for published installs, or latest_version_id for draft installs.

read_skill

Reads one full Skill package version. This response contains the package contents needed to install a skill locally: write skill_md as SKILL.md, then write each returned file under the local skill directory.

Input:

{
  "skill_id": "SKILL_ID",
  "version": "latest"
}

version is optional.

Version value	Meaning
Omitted	Read the latest saved version.
latest	Read the latest saved version.
published	Read the published version.
Positive integer or numeric string	Read that exact saved version.

Structured output:

{
  "skill_id": "SKILL_ID",
  "name": "skill-name",
  "directory_name": "skill-name",
  "description": "What this skill does and when to use it.",
  "version_id": "VERSION_ID",
  "version": 2,
  "latest_version": 2,
  "published_version": 1,
  "is_published_version": false,
  "has_unpublished_changes": true,
  "skill_md": "---\nname: skill-name\ndescription: What this skill does and when to use it.\n---\n\nWrite the Skill package instructions here.\n",
  "files": [
    {
      "path": "references/example.md",
      "content": "Reference text",
      "media_type": "text/markdown"
    },
    {
      "path": "assets/example.png",
      "content_base64": "iVBORw0KGgo=",
      "media_type": "image/png"
    }
  ],
  "created_at": "2026-06-20T16:00:00Z",
  "updated_at": "2026-06-23T16:00:00Z",
  "version_created_at": "2026-06-23T16:00:00Z",
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23",
  "status": "live",
  "publication_status": "unpublished_changes",
  "can_read": true,
  "can_draft": true,
  "can_edit": true,
  "can_publish": false
}

Before editing, read with version: "latest" and pass the returned version as expected_version to write_skill.

When installing a skill locally, prefer version: "published" unless the user explicitly asks for the latest saved draft. Use directory_name for the local directory name, write skill_md to SKILL.md, write text content files as-is, and decode content_base64 before writing binary files. directory_name is Alignbase’s virtual skill parent directory and matches the frontmatter name.

Local installs should record provenance in the official frontmatter metadata map:

metadata:
  alignbase-origin: "https://app.alignbase.ai"
  alignbase-skill-id: "SKILL_ID"
  alignbase-channel: "published"
  alignbase-version: "1"
  alignbase-version-id: "VERSION_ID"

If the remote SKILL.md already has metadata, preserve existing keys and add or update only the Alignbase keys. If it has no metadata, add the map. Do not add custom top-level frontmatter fields for Alignbase provenance.

To update a local install, call list_skills, match by metadata.alignbase-skill-id, and compare the installed metadata.alignbase-version-id to the listed version ID. Published installs compare against published_version_id. Draft installs compare against latest_version_id. If the IDs match, do nothing. If they differ, call read_skill for the same channel and replace the full local package.

create_skill

Creates a new Alignbase Skill package.

Use this only when the user asks to add a Skill package.

Input:

{
  "skill_md": "---\nname: skill-name\ndescription: What this skill does and when to use it.\n---\n\nWrite the Skill package instructions here.\n",
  "files": [
    {
      "path": "references/example.md",
      "content": "Reference text",
      "media_type": "text/markdown"
    }
  ],
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23"
}

Required fields:

• skill_md

Optional fields:

• files
• review_by, in YYYY-MM-DD format
• expires_at, in YYYY-MM-DD format

skill_md rules:

• Must start with YAML frontmatter.
• Frontmatter must close with ---.
• Frontmatter must include name and description.
• name must use lowercase letters, numbers, and single hyphens, and cannot exceed 64 characters.
• description cannot be empty and cannot exceed 1024 characters.
• compatibility, when present, cannot exceed 500 characters.
• metadata, when present, may contain arbitrary YAML values.
• license and allowed-tools are accepted frontmatter fields.

File rules:

• Do not include SKILL.md in files. Send it as skill_md.
• File paths cannot be absolute, contain .., use backslashes, contain null bytes, or need path normalization.
• File paths are relative to the virtual skill directory named by directory_name.
• File paths cannot exceed 512 characters.
• File paths must be unique.
• Each file must have exactly one non-empty value, either content or content_base64.
• Use content for text files and content_base64 for binary files.
• media_type, when present, cannot exceed 255 characters.
• SKILL.md cannot exceed 1 MiB.
• A skill version cannot include more than 500 package files.
• A package file cannot exceed 2 MiB decoded.
• Total decoded package content, including SKILL.md, cannot exceed 3 MiB.

Role and date rules match context creation through write_context_alignment.

Structured output:

{
  "skill_id": "SKILL_ID",
  "name": "skill-name",
  "directory_name": "skill-name",
  "version_id": "VERSION_ID",
  "version": 1,
  "created": true
}

New skills are saved as latest versions. They do not become the published version until publish_skill succeeds.

write_skill

Replaces the full package for an existing Skill.

This is not a patch tool. Send the complete desired SKILL.md and complete desired file list.

Input:

{
  "skill_id": "SKILL_ID",
  "expected_version": 2,
  "skill_md": "---\nname: skill-name\ndescription: Updated description.\n---\n\nUpdated Skill package instructions.\n",
  "files": [],
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23"
}

Required fields:

• skill_id
• expected_version
• skill_md

Optional fields:

• files
• review_by
• expires_at

Rules:

• Requires a write-capable connection.
• Requires Editor or higher on the Skill.
• expected_version must be positive.
• If expected_version is stale, the write fails with a version conflict.
• Permissions and routes stay unchanged.
• A write saves a new latest version when skill_md or files differ from the latest saved version.
• Package validation matches create_skill.
• If only metadata changes, the call returns the existing latest version and updated: true.
• If the replacement package and metadata match the latest saved state, the call returns updated: false.

Structured output:

{
  "skill_id": "SKILL_ID",
  "name": "skill-name",
  "directory_name": "skill-name",
  "version_id": "VERSION_ID",
  "version": 3,
  "updated": true
}

publish_skill

Publishes a saved Skill version.

Input:

{
  "skill_id": "SKILL_ID",
  "version": "latest"
}

version is optional.

Version value	Meaning
Omitted	Publish the latest saved version.
latest	Publish the latest saved version.
Positive integer or numeric string	Publish that exact saved version.

Structured output:

{
  "skill_id": "SKILL_ID",
  "name": "skill-name",
  "version_id": "VERSION_ID",
  "version": 3,
  "published": true
}

Rules:

• Requires a write-capable connection.
• Requires Publisher or higher on the Skill.
• published: false means the requested version was already published.

create_skill_draft

Proposes a draft SKILL.md replacement for one skill. Skill drafts do not include package files and do not create saved versions.

Input:

{
  "skill_id": "SKILL_ID",
  "base_version": 2,
  "skill_md": "---\nname: skill-name\ndescription: Updated description.\n---\n\nProposed Skill package instructions.\n",
  "rationale": "Optional short reason"
}

Structured output:

{
  "draft_id": "DRAFT_ID",
  "skill_id": "SKILL_ID",
  "base_version": 2,
  "created": true
}

Rules:

• Requires write-capable OAuth scope.
• Requires Proposer or higher on the Skill.
• base_version must be positive and should come from read_skill or list_skills.
• skill_md must pass the same frontmatter validation used by write_skill.

list_skill_drafts

Lists open drafts for one skill.

Input:

{
  "skill_id": "SKILL_ID"
}

Structured output:

{
  "drafts": [
    {
      "draft_id": "DRAFT_ID",
      "skill_id": "SKILL_ID",
      "base_version": 2,
      "current_version": 3,
      "is_stale": true,
      "author_name": "Abe Wheeler",
      "author_email": "[email protected]",
      "agent_name": "Codex",
      "rationale": "Optional short reason",
      "created_at": "2026-06-23T16:00:00Z",
      "created_by_this_agent": true
    }
  ]
}

read_skill_draft

Reads one open skill draft.

Input:

{
  "draft_id": "DRAFT_ID"
}

Structured output:

{
  "draft_id": "DRAFT_ID",
  "skill_id": "SKILL_ID",
  "base_version": 2,
  "current_version": 3,
  "is_stale": true,
  "skill_md": "---\nname: skill-name\ndescription: Updated description.\n---\n\nProposed Skill package instructions.\n",
  "author_name": "Abe Wheeler",
  "author_email": "[email protected]",
  "agent_name": "Codex",
  "rationale": "Optional short reason",
  "created_at": "2026-06-23T16:00:00Z",
  "created_by_this_agent": true
}

Draft authors can read their own open drafts. Agents with publish access on the skill can also read open drafts for review.

list_memories

Lists every active Memory the calling agent may read through direct or Group permission. Routing state is included but does not filter the list.

Input:

{}

Each result includes memory_id, name, version_id, version, assignment_state, and can_write. assignment_state is available when the Memory is permitted but not directly or indirectly routed, otherwise it is enabled or required.

create_memory

Creates a Memory when the agent has Create permission on the Memory Resource type.

Input:

{
  "name": "Release working state",
  "content": "Initial concise working recall"
}

The new Memory is not automatically routed. Its ownership follows the normal agent-created Resource rules. Admins manage its permissions and routes separately in the web app.

read_memory

Reads one permitted Memory by ID and returns the latest version needed for a safe write.

Input:

{
  "memory_id": "MEMORY_ID"
}

Structured output:

{
  "name": "Working Memory",
  "content": "Current working state...",
  "version_id": "VERSION_ID",
  "version": 3,
  "can_write": true,
  "assignment_state": "required",
  "memory_id": "MEMORY_ID"
}

Rules:

• Reading requires Viewer or higher on the requested Memory.
• assignment_state reports available, enabled, or required independently from permission.
• can_write reflects whether the agent has Editor or higher on that Memory.
• memory_id may be omitted only for compatibility when exactly one Memory is readable. New clients should always send it.

write_memory

Replaces the full content of one permitted Memory. This is not a patch tool.

Input:

{
  "memory_id": "MEMORY_ID",
  "expected_version": 3,
  "content": "Full replacement Memory content"
}

Structured output:

{
  "name": "Working Memory",
  "memory_id": "MEMORY_ID",
  "version_id": "NEW_VERSION_ID",
  "version": 4,
  "updated": true
}

Rules:

• Requires Editor or higher on the requested Memory. The Memory does not need to be routed.
• Uses context.read; it does not need context.write.
• memory_id identifies the exact file to replace.
• expected_version must be the latest positive version returned by list_memories, read_memory, or get_current_context.
• The server verifies the Memory ID, live Editor permission, and current version before writing. If another user changes the Memory or Editor permission is revoked after the read, the write fails without changing the file.
• If the Memory content changed, read it again, preserve relevant changes, then retry with the new version.
• expected_revision remains a deprecated compatibility input. New clients should use memory_id and expected_version.
• Writes create live Memory versions immediately. Memory has no draft, review, or publish step.
• Identical replacement content returns updated: false without creating another version.
• Memory content must be 25 KB or smaller.

Version Model

Alignbase stores full snapshots for context alignments, Skill packages, and Memory.

Concept	AGENTS.md and Skills	Memory
Latest saved version	The newest saved version of the context alignment or Skill.	The live working version.
Published version	The version eligible for delivery when the entity is active and routed.	Not used.
Unpublished changes	Latest saved version differs from the published version, or no published version exists.	Not used. Every successful changed write becomes live immediately.
Safe write token	Latest numeric expected_version.	Memory ID plus latest numeric expected_version.

AGENTS.md and Skill reads can target latest, published, or an exact version. Their writes either create a new latest saved version or return the current latest version as a no-op. Publishing chooses which saved version goes live for matching agents. Memory reads always return the assigned live version, and changed writes become live immediately.

Audit Records

Context MCP calls create access and context request records. Context read records include the tool name, agent ID, token ID, context alignment IDs, version IDs, version numbers, and request metadata.

Context write records include before and after version references when relevant. Context alignment writes also use the underlying context service audit path, so state changes stay tied to the agent owner and the MCP agent.

Skill writes use the skill service audit path. Skill audit metadata includes the MCP tool, tenant, agent, token, owner, package version, and freshness fields.

Memory reads and writes record the Memory ID, before and after version references, result, and whether a write changed the content.

Common Errors

Error text	Cause	What to do
invalid MCP token metadata	Connection metadata is missing required tenant, agent, token, or owner values.	Reconnect the agent.
invalid context_alignment_id	A context alignment tool received a malformed context alignment UUID.	Run list_context_alignments and use the returned context_alignment_id.
invalid skill_id	A skill tool received a malformed skill UUID.	Run list_skills and use the returned id.
invalid memory_id	A Memory tool received a malformed Memory UUID.	Run list_memories and use a returned memory_id.
memory_id is required when more than one Memory is readable	read_memory omitted the ID when several Memories are permitted.	Choose a Memory from list_memories and pass its ID.
expected_version must be positive	write_memory omitted a current positive version.	Read the Memory and pass its latest version.
invalid expected_revision: read Memory again before writing	A legacy compatibility revision is malformed.	Use memory_id and expected_version instead.
memory_changed: read Memory again, preserve relevant changes, and retry	Another write changed the Memory after the agent read it.	Read that Memory again, merge the useful update, and retry once.
memory_write_forbidden: ...	The agent lacks current Editor permission on the Memory.	Keep the Memory read-only and do not retry the write.
context alignment not found	The context alignment does not exist or the agent cannot read or write it.	Run list_context_alignments and check the agent’s effective role.
skill not found	The skill does not exist or the agent cannot read or write it.	Run list_skills and check the agent’s effective role.
this context alignment has no published version	read_context_alignment requested published, but the context alignment has not been published.	Read latest or publish a version first.
this skill has no published version	read_skill requested published, but the skill has not been published.	Read latest or publish a version first.
context alignment version not found	The requested version number does not exist.	Run list_context_alignments or read latest.
skill version not found	The requested skill version number does not exist.	Run list_skills or read latest.
version must be latest, published, or a positive version number	A read tool received an invalid version selector.	Use latest, published, or a positive version number.
version must be latest or a positive version number	A publish tool received an invalid version selector.	Use latest or a positive version number.
version conflict: read the context alignment again before writing	expected_version is stale.	Read latest, merge the change, then write with the new version number.
version conflict: read the skill again before writing	expected_version is stale.	Read latest, merge the change, then write with the new version number.
expected_version must be 0 for create or positive for write	expected_version is less than 0.	Use 0 to create or the latest version number to write an existing context alignment.
context_alignment_id is required when expected_version is greater than 0	A context alignment write request has no context_alignment_id.	Send the context alignment ID when writing an existing context alignment.
context_alignment_id must be omitted when expected_version is 0	A create request included a context_alignment_id.	Omit context_alignment_id when creating a new context alignment.
title required	The create title is empty after trimming.	Send a non-empty title.
title too long	The create title is longer than 200 characters.	Shorten the title.
content is required	Create content is empty.	Send the full markdown content.
invalid skill package: ...	skill_md or files failed package validation.	Fix the YAML frontmatter, name, description, or package files.
forbidden	The agent lacks the role required for the requested operation.	Update the relevant role in Alignbase or choose a Resource the agent can use.
review_by must use YYYY-MM-DD format	review_by is present but not a date in YYYY-MM-DD format.	Send review_by as YYYY-MM-DD or omit it.
expires_at must use YYYY-MM-DD format	expires_at is present but not a date in YYYY-MM-DD format.	Send expires_at as YYYY-MM-DD or omit it.
expires_at cannot be before review_by	Staleness dates are invalid.	Use dates in order.

Recommended Agent Behavior

At the start of a conversation:

1. Call get_current_context.
2. If it succeeds, follow the returned published AGENTS.md and Skills, and use each routed Memory as scoped working recall.
3. If it fails, tell the user Alignbase context could not be loaded and ask whether to continue without it. Wait for confirmation before answering the original request.

When editing context:

1. Use list_context_alignments to find the context alignment unless you already have the ID.
2. Use read_context_alignment with version: "latest".
3. Send the full replacement content to write_context_alignment.
4. Pass the latest version as expected_version.
5. Publish only when the user asked for the change to go live.
6. Leave Group, permission, and route changes to the Alignbase UI.

When creating context:

1. Use write_context_alignment.
2. Omit context_alignment_id.
3. Send expected_version: 0, title, and full content.
4. Set publish: true only when the user asked for the new context to go live and the agent has the required capability on All Alignments.

When working with skills:

1. Use list_skills to find the skill unless you already have the ID.
2. Use read_skill with version: "latest".
3. Send the full replacement package to write_skill.
4. Pass the latest version as expected_version.
5. Publish only when the user asked for the skill version to go live.
6. Leave Group, permission, and route changes to the Alignbase UI.

When maintaining Memory:

1. Use the routed Memories from get_current_context, or call list_memories to discover other permitted files.
2. Before finishing meaningful work, decide whether current working state, a user correction, a stable preference, unfinished work, a failed approach, or a known trap would help the next session.
3. If can_write is false or the context says writes are forbidden, use Memory as read-only.
4. Before writing, call read_memory with the selected memory_id to load the latest file.
5. When writing is allowed, send memory_id, the exact latest version as expected_version, and the full concise replacement to write_memory without asking the user.
6. If Memory changed, read it again, preserve relevant changes, and retry. If Editor permission changed, stop.
7. Do not store secrets, full conversations, source material, published instructions, Skills, or canonical company knowledge in Memory.

When installing a skill locally:

1. Use list_skills to find the skill unless you already have the ID.
2. Use read_skill with version: "published" unless the user asked for a draft.
3. Create a local skill directory named from directory_name.
4. Write skill_md as SKILL.md.
5. Write each returned package file by relative path, using content for text and decoded content_base64 for binary files.
6. Keep every package file under the local skill directory. Do not write absolute paths or parent directory paths.
7. Add or update Alignbase provenance under SKILL.md frontmatter metadata, not as top-level frontmatter fields.

When updating local skill installs:

1. Read each installed skill’s metadata.alignbase-skill-id, metadata.alignbase-channel, and metadata.alignbase-version-id.
2. Use list_skills to check the remote skill version IDs the agent can read.
3. For published installs, compare the local metadata.alignbase-version-id to published_version_id.
4. For draft installs, compare the local metadata.alignbase-version-id to latest_version_id.
5. If the version IDs match, leave the local package unchanged.
6. If the version IDs differ, call read_skill for the same channel and replace the full local package.