Alignbase MCP Agent API Reference

This is the current reference for the Alignbase MCP agent API for managed Knowledge, Skills, Memory, Artifacts, messages, and Activity.

The production app base URL is:

https://app.alignbase.com

The MCP endpoint is:

https://app.alignbase.com/mcp

Existing clients configured for https://app.alignbase.ai/mcp continue to work during the domain migration. New clients should use the .com endpoint.

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.

The app and MCP tools call this Resource Knowledge. Knowledge may contain reference information or must-follow instructions. Must-follow Knowledge with Always routing provides AGENTS.md behavior. Use the Knowledge tool names and knowledge_id.

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.com
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 Knowledge and Skill write permissions can take effect.
activity.write	Required for installation capability and lifecycle event tools.

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.com/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 Knowledge, 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 Knowledge 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 Always 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 Knowledge Resource 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, mark read	Always route on active context; issues new messages
list_knowledge	Read	Viewer or higher on the Knowledge
read_knowledge	Read	Viewer or higher on the Knowledge
write_knowledge	Write	Editor on a Knowledge, or Editor on All Knowledge to create
publish_knowledge	Write	Publisher or higher on the Knowledge
create_knowledge_draft	Write	Proposer or higher on the Knowledge
propose_knowledge	Write	Draft access to Default for a new Knowledge proposal
list_knowledge_drafts	Read	Viewer or higher on the Knowledge
read_knowledge_draft	Read	Draft author or Publisher on the Knowledge
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
read_context_attachment	Read	Live access to the requested exact Resource version
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
list_artifacts	Read	Viewer or higher on each listed Artifact
read_artifact	Read	Viewer or higher on the requested Artifact
write_artifact	Write	Artifact Create permission or Editor on an existing Artifact
list_context_recipients	Read	Agents and Groups the caller may message
send_context	Write	Can message, plus Can share and access for each Artifact
read_inbox	Read, mark read	The connected agent’s inbox
report_installation_capabilities	Write	activity.write scope and an authenticated agent
record_activity_event	Write	activity.write scope, registered installation, allowed event
start_hook_session	Write	activity.write scope and an installed authenticated hook
record_hook_activity_event	Write	activity.write scope and an installed authenticated hook

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 Knowledge. 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 skill_md and the attachment manifest, then write skill_md as SKILL.md and fetch each attachment under the 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 Knowledge 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 Knowledge, Skills, and Memory. Follow must-follow Knowledge within its authorized scope. Treat informational Knowledge as reference material. Follow authorized Skill 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="enabled" can_write="true">

Current working state...

</alignbase_memory>

## Knowledge

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

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

Context content...

</alignbase_knowledge>

Rules:

• Returns non-expired published Knowledge and Skill versions only.
• Returns each active published Knowledge with an Always route, regardless of the receiving agent’s repository permission.
• Lists each active published Skill with an Always 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 Knowledge. Skill contents are loaded separately with read_skill.
• Wraps each Knowledge in a protected <alignbase_knowledge> 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 Knowledge, Skill, and Memory version metadata.

list_knowledge

Lists Knowledge on which the calling agent has Viewer or higher.

Input:

{}

Structured output:

{
  "knowledge": [
    {
      "knowledge_id": "KNOWLEDGE_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 Knowledge 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 Knowledge.
can_edit	True only when the connection can write and the agent has Editor or higher on the Knowledge.
can_publish	True only when the connection can write and the agent has Publisher or higher on the Knowledge.

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

read_knowledge

Reads one full Knowledge version.

Input:

{
  "knowledge_id": "KNOWLEDGE_ID",
  "version": "latest"
}

version is optional.

Viewer or higher permission allows every selector below. An active Always 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:

{
  "knowledge_id": "KNOWLEDGE_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_knowledge.

write_knowledge

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

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 Knowledge input:

{
  "knowledge_id": "KNOWLEDGE_ID",
  "expected_version": 4,
  "content": "Full replacement markdown content",
  "publish": false
}

Required fields:

• expected_version
• content

Optional fields:

• knowledge_id, required when expected_version is greater than 0
• title, required when expected_version is 0
• authority, either informational or must_follow. New Knowledge defaults to informational; omitted authority on updates preserves the existing value.
• publish, set to true only when the user wants the written version published immediately
• review_by, only used when creating a Knowledge with expected_version: 0
• expires_at, only used when creating a Knowledge with expected_version: 0

Rules:

• Requires a write-capable connection.
• Use expected_version: 0 to create a new Knowledge. Omit knowledge_id in this path.
• Creating requires Editor or higher on All Knowledge. The new Knowledge is not routed automatically.
• Use a positive expected_version to write an existing Knowledge. knowledge_id is required in this path.
• Existing writes require Editor or higher on the Knowledge.
• 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 content or authority differs from the latest saved version.
• If the content and authority match the latest saved version, the call returns updated: false and does not create a new version.
• Empty string content is accepted for existing writes and replaces the Knowledge 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 Knowledge. Creating and publishing a new Knowledge requires the corresponding capabilities on All Knowledge.

Structured output:

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

publish_knowledge

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

Input:

{
  "knowledge_id": "KNOWLEDGE_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:

{
  "knowledge_id": "KNOWLEDGE_ID",
  "title": "Context title",
  "version_id": "VERSION_ID",
  "version": 5,
  "published": true
}

Rules:

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

create_knowledge_draft

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

Input:

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

Structured output:

{
  "draft_id": "DRAFT_ID",
  "knowledge_id": "KNOWLEDGE_ID",
  "base_version": 4,
  "created": true
}

Rules:

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

propose_knowledge

Proposes brand-new Knowledge for human review. Input includes a title, full Markdown content, optional rationale, authority (informational or must_follow), and optional v1 attachments. The response contains a proposal_id. This creates no saved or published Knowledge until a human accepts the proposal. The agent needs a write-capable connection and Draft access to Default.

list_knowledge_drafts

Lists open drafts for one Knowledge.

Input:

{
  "knowledge_id": "KNOWLEDGE_ID"
}

Structured output:

{
  "drafts": [
    {
      "draft_id": "DRAFT_ID",
      "knowledge_id": "KNOWLEDGE_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_knowledge_draft

Reads one open Knowledge draft.

Input:

{
  "draft_id": "DRAFT_ID"
}

Structured output:

{
  "draft_id": "DRAFT_ID",
  "knowledge_id": "KNOWLEDGE_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 Knowledge 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_knowledge, except each item is a Skill package instead of a Knowledge.

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. Write skill_md as SKILL.md, then fetch each attachment with read_context_attachment and write it 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",
  "attachment_format": "v1",
  "attachments": [
    {
      "path": "references/example.md",
      "media_type": "text/markdown",
      "size": 14,
      "digest_encoding": "text"
    },
    {
      "path": "assets/example.png",
      "media_type": "image/png",
      "size": 1024,
      "digest_encoding": "binary"
    }
  ],
  "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, then download and decode each attachment. 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/mcp"
  alignbase-skill-id: "SKILL_ID"
  alignbase-channel: "published"
  alignbase-version: "1"
  alignbase-version-id: "VERSION_ID"

Copy these keys from the read_skill install metadata. The origin remains the .ai MCP URL on both production hosts so existing installs stay recognizable after switching hosts. 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.

read_context_attachment

Reads one attachment from an exact saved Knowledge, Skill, or Artifact version. Package reads return attachment metadata only, so use this tool to fetch the bytes.

Input:

{
  "context_type": "skill",
  "context_id": "SKILL_ID",
  "version": 2,
  "path": "references/example.md",
  "offset": 0
}

Rules:

• context_type must be knowledge, skill, or artifact.
• context_id, version, and path must match a manifest returned by the corresponding read tool.
• version must be an exact positive number, never latest or published.
• Start with offset: 0. Each response contains at most 256 KiB.
• When eof is false, call the tool again with offset set to next_offset and append the decoded bytes.
• Access is checked on every call. Route-only Knowledge and Skill readers may fetch only the current published version.

Structured output:

{
  "data_base64": "UmVmZXJlbmNlIHRleHQ=",
  "offset": 0,
  "next_offset": 14,
  "size": 14,
  "eof": true,
  "media_type": "text/markdown",
  "version_id": "VERSION_ID"
}

Decode data_base64 after joining all chunks in offset order. Verify version_id stays unchanged across chunks.

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",
  "attachments": [
    {
      "path": "references/example.md",
      "data_base64": "UmVmZXJlbmNlIHRleHQ="
    }
  ],
  "review_by": "2026-07-23",
  "expires_at": "2026-08-23"
}

Required fields:

• skill_md

Optional fields:

• attachments
• 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 attachments. 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 attachment must have non-empty data_base64.
• media_type is detected from the decoded bytes.
• 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_knowledge.

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. Omit attachments to retain them, pass [] to clear them, or send a complete replacement set.

Input:

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

Required fields:

• skill_id
• expected_version
• skill_md

Optional fields:

• attachments
• 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 attachments 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 always.

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": "always",
  "memory_id": "MEMORY_ID"
}

Rules:

• Reading requires Viewer or higher on the requested Memory.
• assignment_state reports available or always independently from permission.
• can_write reflects whether the agent has Editor or higher on that Memory.

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.
• 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.

Artifacts

Artifacts hold explicit inputs, deliverables, and handoffs as versioned Markdown and files. They are data, with no instruction authority or automatic route. Every save creates an immutable full package version. External links in Markdown remain links; Alignbase does not snapshot their targets.

• list_artifacts returns the Artifacts this agent may read, with each Artifact ID, name, and current version.
• read_artifact takes artifact_id and an optional version. Omit version or pass "latest" for the latest saved package; pass a positive integer for an exact version. The response includes Markdown, a file manifest, version ID, package digest, and provenance when present. Artifact versions have no published selector.
• write_artifact takes a name, Markdown, optional files, and expected_version. Use 0 to create or the exact latest version to replace a package. Omitted attachments retain existing files; [] clears them; a supplied array replaces the full file set. source_task follows the same preserve-on-omit rule and can be cleared with an explicit empty string. Creation requires Artifact Create permission; updates require Editor access.

read_context_attachment fetches the bytes named by an Artifact manifest using context_type: "artifact", the Artifact ID, exact version, and relative path. Each request rechecks live access. Attachment chunks are base64 encoded and bounded to 256 KiB.

Messages

Messages let agents send a note and exact Artifact versions to permitted agents or Groups. Sending checks every recipient and Artifact, grants only the allowed Viewer or Editor access, stores the message, and records audit evidence in one transaction. A Group send targets its current active agents; Group access also covers future members. Sending does not start an agent.

• list_context_recipients lists the agents and Groups this caller may message.
• send_context takes recipients, optional message and artifacts, and an idempotency_key UUID. Each Artifact entry names its ID, optional version, and Viewer or Editor access. Omitted versions are pinned to the latest at send time. Reuse the same key and input for a retry.
• read_inbox returns up to 20 messages for the connected agent. A full unread page is marked read when issued. include_read: true supports rereads with offset and next_offset. Each attachment reference includes its pinned Artifact version, subject to a fresh access check before the files are returned.

get_current_context also includes a bounded set of new messages. A response being issued or marked read does not prove the model consumed the message or completed a request.

Activity tools

Activity tools require the activity.write OAuth scope and record limited client-reported lifecycle evidence. They do not take transcripts, private reasoning, tool payloads, or arbitrary environment values. Client-reported events are not vendor attestation or proof of model consumption.

• report_installation_capabilities registers the integration, transport, and supported capability names after installation or a connection test. It returns a local_installation_id to reuse.
• record_activity_event records an allowed event for a previously reported installation when Activity is enabled. It takes that installation ID and an event object.
• start_hook_session is for an installed authenticated session-start or prompt hook. It registers native lifecycle coverage, records the start once, and returns current context.
• record_hook_activity_event is for an installed authenticated lifecycle hook. It records one native event and refreshes the adapter’s declared coverage.

Version Model

Alignbase stores full snapshots for Knowledge, Skill packages, and Memory.

Concept	Knowledge and Skills	Memory
Latest saved version	The newest saved version of the Knowledge 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.

Knowledge 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, Knowledge IDs, version IDs, version numbers, and request metadata.

Knowledge write records include before and after version references when relevant, 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 knowledge_id	A Knowledge tool received a malformed Knowledge UUID.	Run list_knowledge and use the returned knowledge_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.
expected_version must be positive	write_memory omitted a current positive version.	Read the Memory and pass its latest version.
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.
Knowledge not found	The Knowledge does not exist or the agent cannot read or write it.	Run list_knowledge 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 Knowledge has no published version	read_knowledge requested published, but the Knowledge 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.
Knowledge version not found	The requested version number does not exist.	Run list_knowledge 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 Knowledge 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 Knowledge.
knowledge_id is required when expected_version is greater than 0	A Knowledge write request has no knowledge_id.	Send the Knowledge ID when writing an existing Knowledge.
knowledge_id must be omitted when expected_version is 0	A create request included a knowledge_id.	Omit knowledge_id when creating a new Knowledge.
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 attachments failed package validation.	Fix the YAML frontmatter, name, description, or package attachments.
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 Knowledge 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_knowledge to find the Knowledge unless you already have the ID.
2. Use read_knowledge with version: "latest".
3. Send the full replacement content to write_knowledge.
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_knowledge.
2. Omit knowledge_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 Knowledge.

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. Fetch each attachment with read_context_attachment, decode data_base64, and write it to its relative path.
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.