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, tagged, 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 read routed AGENTS.md and Skills, read assigned Memory, and write Memory when permitted.
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.

Tags decide which context alignments and Skills an agent can see. If an agent and an entity share a tag, the agent can read that entity.

AGENTS.md and Skill writes need more. The agent must have write access to the relevant tags and the matching Alignbase permission for the tool, such as Create context, Edit context, or Publish context. Alignbase checks those permissions when the MCP endpoint handles the call, so a connected agent may still be denied by a specific tool.

Memory does not use tags or the AGENTS.md and Skill permission set. Every new agent starts with a blank, writable <Agent Name>'s Memory file. An admin can assign a different file and controls that agent’s Write memories permission. Every assigned agent can read its Memory. Several agents can share one Memory file.

MCP tools do not create tags, change tag assignments, create or assign Memory, or change Memory write access. New context alignments and Skills are created on Default; write tools keep the current tags.

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 read_memory, or the conditional Memory guidance in get_current_context, to decide whether the current agent can update its assigned Memory.

Tool Summary

Tool	Read or write	Alignbase-side checks
get_current_context	Read	Read access through shared tags on non-expired published context
list_context_alignments	Read	Read access through shared tags
read_context_alignment	Read	Read access through shared tags
write_context_alignment	Write	Create on Default, or edit through current context alignment tags
publish_context_alignment	Write	Publish context, plus write access to the context alignment tags
create_context_alignment_draft	Write	Propose draft context, plus draft access to the context alignment tags
list_context_alignment_drafts	Read	Read access through shared tags
read_context_alignment_draft	Read	Draft author or publish access on the context alignment
list_skills	Read	Read access through shared tags
read_skill	Read	Read access through shared tags
create_skill	Write	Create context, plus write access to Default
write_skill	Write	Edit context, plus write access to the skill tags
publish_skill	Write	Publish context, plus write access to the skill tags
create_skill_draft	Write	Propose draft context, plus draft access to the skill tags
list_skill_drafts	Read	Read access through shared tags
read_skill_draft	Read	Draft author or publish access on the skill
read_memory	Read	Read the calling agent’s directly assigned Memory
write_memory	Write	Assigned Memory plus the calling agent’s Write memories permission

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.

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 its directly assigned 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."

## Memory

<alignbase_memory id="MEMORY_ID" name="Working Memory" version="3" version_id="VERSION_ID" revision="OPAQUE_REVISION">

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 tag; they end at the closing tag.

<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 context alignments sharing one or more tags with the calling agent.
• Lists published Skills sharing one or more tags with the calling agent, including each Skill’s name and description.
• Includes the current version of the calling agent’s assigned Memory, if any, with the opaque revision required for a safe write.
• Adds Memory maintenance instructions only when that agent can write. If writing is forbidden, it includes only read-only guidance.
• 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 tags in user content are escaped.
• Wraps assigned Memory in a protected <alignbase_memory> boundary. Reserved boundary tags 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 the calling agent can read through shared tags.

Input:

{}

Structured output:

{
  "context_alignments": [
    {
      "context_alignment_id": "CONTEXT_ALIGNMENT_ID",
      "title": "Context title",
      "tags": ["Default"],
      "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 can propose drafts through the context alignment tags.
can_edit	True only when the connection can write, the agent has Edit context, and the agent can write the context alignment tags.
can_publish	True only when the connection can write, the agent has Publish context, and the agent can write the context alignment tags.

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.

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",
  "tags": ["Default"],
  "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 read/write agent permission.
• Use expected_version: 0 to create a new context alignment. Omit context_alignment_id in this path.
• Creating assigns Default and requires write access to Default.
• Use a positive expected_version to write an existing context alignment. context_alignment_id is required in this path.
• Existing writes require write access to the context alignment tags.
• If expected_version is stale, the write fails with a version conflict.
• Tags 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 publish access through the context alignment tags. For creation, that means publish access on Default.

Structured output:

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

publish_context_alignment

Publishes a saved context alignment version so agents with matching tags receive it through get_current_context.

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 Publish context permission.
• Requires write access to the context alignment tags.
• 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 draft access through the context alignment tags.
• 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 the calling agent can read through shared tags.

Input:

{}

Structured output:

{
  "skills": [
    {
      "id": "SKILL_ID",
      "name": "skill-name",
      "directory_name": "skill-name",
      "description": "What this skill does and when to use it.",
      "tags": ["Default"],
      "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.",
  "tags": ["Default"],
  "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.

Tag 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,
  "tags": ["Default"],
  "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 Edit context permission.
• Requires write access to the skill tags.
• expected_version must be positive.
• If expected_version is stale, the write fails with a version conflict.
• Tags 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",
  "tags": ["Default"],
  "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 Publish context permission.
• Requires write access to the skill tags.
• 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 draft access through the skill tags.
• 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.

read_memory

Reads the calling agent’s assigned Memory and returns the revision needed for a safe write.

Input:

{}

Structured output when Memory is assigned:

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

When no Memory is assigned, the tool returns:

{
  "name": "",
  "content": "",
  "version_id": "",
  "version": 0,
  "revision": "",
  "can_write": false,
  "assigned": false,
  "memory_id": ""
}

Rules:

• Every agent can read its assigned Memory.
• Memory uses a direct agent assignment, not tags.
• can_write reflects the Write memories permission for this agent.
• revision is opaque. Pass it back unchanged to write_memory.

write_memory

Replaces the full content of the calling agent’s assigned Memory. This is not a patch tool.

Input:

{
  "expected_revision": "OPAQUE_REVISION",
  "content": "Full replacement Memory content"
}

Structured output:

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

Rules:

• Requires an assigned Memory and the calling agent’s Write memories permission.
• Uses context.read; it does not need context.write, tag write access, or the AGENTS.md and Skill write permissions.
• expected_revision must be the exact value returned by the latest get_current_context or read_memory.
• The server verifies the assignment, write permission, Memory ID, and current version together before writing. If another user changes the Memory, reassigns the agent, or revokes write access after the read, the write fails without changing either file.
• If the Memory content changed, read it again, preserve relevant changes, then retry with the new revision.
• If the assignment changed, read the newly assigned Memory and decide whether the update still belongs there. Never copy the old update into the new file automatically.
• 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 or use when the entity is not expired and shares tags with the agent.	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.	Exact opaque expected_revision, which also protects the assignment.

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.
expected_revision is required	write_memory did not receive a revision.	Read Memory and pass its exact revision.
invalid expected_revision: read Memory again before writing	The Memory revision is malformed.	Run read_memory, preserve relevant changes, and retry with its revision.
memory_changed: read Memory again, preserve relevant changes, and retry	Another write changed the assigned Memory after the agent read it.	Read Memory again, merge the useful update, and retry once.
memory_assignment_changed: ...	The agent’s Memory assignment changed after the read.	Read the newly assigned Memory and decide whether the update belongs there.
memory_write_forbidden: ...	An admin turned off Write memories for this agent.	Keep 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 tag access.
skill not found	The skill does not exist or the agent cannot read or write it.	Run list_skills and check tag access.
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.
tag "..." requires write tag access	The agent tried to create or write through a tag it cannot write.	Update tag permissions in Alignbase or choose an entity the agent can write.
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.
requires the ... agent permission	The agent lacks the relevant Alignbase permission.	Update the agent permissions in Alignbase.

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 assigned Memory as 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 tag assignment 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 publish access on Default.

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 tag assignment changes to the Alignbase UI.

When maintaining Memory:

1. Use the assigned Memory from get_current_context, or call read_memory.
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. When writing is allowed, send the full concise replacement to write_memory without asking the user.
5. Pass the exact latest revision as expected_revision.
6. If Memory changed, read it again, preserve relevant changes, and retry. If the assignment or write 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.