# Axis (npm · @virsanghavi/axis-server)

Coding agents from Claude Code, Cursor and Codex claim jobs and lock files on one shared board.

- Trust score: 23/100 (low)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `useaxis.dev`: 38/100, [markdown](https://verifymcp.io/servers/dev-useaxis-axis/api-mcp.md), [page](https://verifymcp.io/servers/dev-useaxis-axis/api-mcp)
- npm · `@virsanghavi/axis-server`: 23/100 (this document), [markdown](https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server.md), [page](https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server)

## Channel facts

- Registry: `npm`
- Package: `@virsanghavi/axis-server`
- Version: `1.14.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 47/100
  - Malware scan not yet available for this package.
  - Only part of the dependency tree could be resolved (149 of 150), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (149 of 150), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (AGPL-3.0-only).
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 0/100
  - Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- **Tool Coverage**: 0/100
  - Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- **Capabilities**: 0/100
  - Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.

**Unverified: 4 categories.** Categories scored 0 because our sandbox run of this package has not given us the schema these checks need to read. That is a gap on our side rather than a finding about the package, and we only credit what we can confirm, so the score stands at 0 until the capture succeeds. We are working through the fleet, so this normally clears without any action from you.

## Install

### Claude

```bash
claude mcp add dev-useaxis-axis -- npx -y @virsanghavi/axis-server
```

### Codex

```bash
codex mcp add dev-useaxis-axis -- npx -y @virsanghavi/axis-server
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "dev-useaxis-axis": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@virsanghavi/axis-server"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add dev-useaxis-axis --command npx --arg -y --arg @virsanghavi/axis-server
```

### Hermes

```yaml
mcp_servers:
  dev-useaxis-axis:
    command: "npx"
    args: ["-y", "@virsanghavi/axis-server"]
```

### Other

```json
{
  "mcpServers": {
    "dev-useaxis-axis": {
      "command": "npx",
      "args": [
        "-y",
        "@virsanghavi/axis-server"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 23)

First indexed and scored.

## MCP tools (28)

### `read_context` (~128 tokens)

\**READ THIS FIRST** to understand the project's architecture, coding conventions, and active state.
\- Returns the content of core context files like `context.md` (Project Goals), `conventions.md` (Style Guide), or `activity.md`.
\- Usage: Call with `filename='context.md'` effectively.
\- Note: If you need the *current* runtime state (active locks, jobs), use the distinct resource `mcp://context/current` instead.

Input parameters:

- `filename` (string, required): The name of the file to read (e.g., 'context.md', 'conventions.md')

### `update_context` (~193 tokens)

\**APPEND OR OVERWRITE** any shared context file.
\- To update the project soul (context.md / conventions.md), prefer `update_project_soul` instead — it handles both files in one call.
\- Use this tool for other context files (e.g., `activity.md`) or when you need to append to a file.
\- For short-term updates (like 'I just fixed bug X'), use `update_shared_context` (Notepad) instead.
\- Supports `append: true` (default: false) to add to the end of a file.

Input parameters:

- `append` (boolean): Whether to append to the end of the file (true) or overwrite it (false). Default: false.
- `content` (string, required): The new content to write or append.
- `filename` (string, required): File to update (e.g. 'activity.md'). For soul files, prefer update_project_soul instead.

### `get_subscription_status` (~88 tokens)

\**BILLING CHECK**: Returns the user's subscription tier (Pro vs Free), Stripe customer ID, and current period end.
\- If no email is provided, returns the subscription status of the current API key owner.
\- Critical for gating features behind paywalls.

Input parameters:

- `email` (string): Optional. User email to check. If omitted, checks the subscription of the current API key owner.

### `get_usage_stats` (~76 tokens)

\**API USAGE**: Returns token usage and request counts.
\- If no email is provided, returns usage for the current API key owner.
\- Useful for debugging rate limits or explaining quota usage to users.

Input parameters:

- `email` (string): Optional. User email to check. If omitted, checks usage of the current API key owner.

### `search_codebase` (~172 tokens)

\**CODE INTELLIGENCE SEARCH** — does what plain grep can't: returns ranked `file:line` hits PLUS `related` files that historically co-change with each hit, PLUS `definitions` of what the top result calls.
\- Use for 'where is X', 'how is Y done', anything before refactoring, and any time you need to know what code is structurally connected to a match (not just textually present).
\- Hybrid: semantic + full-text + trigram, reranked. Falls back to instant local search offline.
\- For pure literal-string lookups (a specific token or filename), grep is fine — this tool's edge is the related/definitions enrichment.

Input parameters:

- `query` (string, required): Natural-language question or code query (symbol, behavior, or 'where is X done').

### `index_codebase` (~142 tokens)

\**INDEX THE REPO FOR SEARCH**: Walk the project, content-hash every file, and sync changed files into the searchable index so `search_codebase`/`deep_search` work and stay fresh.
\- Incremental: unchanged files are skipped (no re-embedding), deleted files are pruned. Safe and cheap to run often.
\- Run this once to set up search on a new project, and after large changes (e.g. a git pull) to refresh. Single-file edits are picked up by `index_file`.
\- Respects .gitignore and skips binaries/large files. Takes no arguments — it indexes the current project root.

### `search_docs` (~71 tokens)

\**DOCUMENTATION SEARCH**: Searches the official Axis documentation (if indexed).
\- Use this when you need info on *how* to use Axis features, not just codebase structure.
\- Falls back to local RAG search if the remote API is unavailable.

Input parameters:

- `query` (string, required): Natural language search query.

### `propose_file_access` (~347 tokens)

\**CRITICAL: REQUEST FILE LOCK** — call this before EVERY file edit, no exceptions.
\- Returns `GRANTED` if safe to proceed, `REQUIRES_ORCHESTRATION` if another agent holds the lock, or `REJECTED` if you tried to lock a directory.
\- **Lock individual files, not directories.** Directory locks block parallel work and are rejected.
\- Paths can be absolute or relative — they're normalized against the project root.
\- Required: `intent` (descriptive — 'Refactor auth to use JWT', NOT 'editing file') plus `filePath` or `filePaths`. `agentId` is optional (defaults to your session identity).
\- Editing several files? Pass `filePaths` to lock them in ONE call — all-or-nothing, so a partial batch never blocks others.
\- Locks expire after 30 minutes. Use `force_unlock` only as a last resort for crashed agents.
\- **Every lock MUST be released.** `complete_job` releases the locks for that job; `finalize_session` releases everything. Dangling locks block all other agents.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `filePath` (string): One file to lock. Use `filePaths` instead for a multi-file batch.
- `filePaths` (array): Lock several files in one call (all-or-nothing: on any denial, locks granted earlier in the batch are released).
- `intent` (string, required)
- `userPrompt` (string): Optional. The user prompt that triggered this lock, for audit trails. Server captures it best-effort if omitted.

### `release_file_access` (~93 tokens)

\**RELEASE YOUR LOCK**: Release one file lock as soon as you no longer need it.
\- Use this before a job is complete when another agent can safely continue on the file.
\- Only the owning agent can release the lock; use `force_unlock` only for a crashed agent.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `filePath` (string, required)

### `list_locks` (~43 tokens)

\**INSPECT ACTIVE LOCKS**: Return current file locks, owners, intents, and timestamps.
\- Call before planning overlapping work or when a lock conflict needs coordination.

### `verify_file_lock` (~124 tokens)

\**TAMPER CHECK BEFORE WRITING**: Confirm a file you hold a lock on hasn't changed since the lock was granted.
\- Locks are advisory — another process can still edit the file. Call this right before overwriting to avoid clobbering concurrent changes.
\- Returns `OK` (unchanged), `CONFLICT` (modified/deleted — re-read before writing), `NO_LOCK`, or `UNKNOWN` (no fingerprint recorded).

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `filePath` (string, required)

### `list_agents` (~77 tokens)

\**WHO'S ONLINE**: List agents currently active or idle on this project.
\- Use to see your team before posting jobs — idle workers started early show up here, so you don't have to make the user wait for jobs before launching agents.
\- Returns each agent's status (active/idle), last activity, and last-seen time.

### `guarded_write` (~136 tokens)

\**ENFORCED WRITE**: Write a file *through* your lock. The server writes only if you hold the lock AND the file is unchanged since you locked it — otherwise it returns NO_LOCK, DENIED (held by another agent), or CONFLICT (changed underneath you). Use this instead of a raw editor when you want Axis to actually *prevent* clobbering, not just detect it. Refreshes the lock's fingerprint on success.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `content` (string, required): Full new file contents.
- `filePath` (string, required)

### `update_shared_context` (~105 tokens)

\**LIVE NOTEPAD**: The project's short-term working memory.
\- **ALWAYS** call this after completing a significant step (e.g., 'Fixed bug in auth.ts', 'Ran tests, all passed').
\- This content is visible to *all* other agents immediately.
\- Think of this as a team chat or 'standup' update.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `text` (string, required)

### `finalize_session` (~129 tokens)

\**MANDATORY SESSION CLEANUP** — call this automatically when the user's request is fully complete.
\- Archives the current Live Notepad to a permanent session log.
\- **Clears ALL active file locks** and completed jobs. This is your safety net to ensure no dangling locks.
\- Resets the Live Notepad for the next session.
\- Do NOT wait for the user to say 'we are done.' When all tasks are finished, call this yourself.
\- **CRITICAL**: You MUST call this before ending ANY session. Failing to do so leaves file locks that block all other agents.

### `get_project_soul` (~221 tokens)

\**MANDATORY FIRST CALL**: Returns the project's goals, architecture, conventions, and active state.
\- Combines `context.md` (project goals/architecture) and `conventions.md` (coding standards/norms) into a single prompt.
\- You MUST call this as your FIRST action in every new session or task — before reading files, before responding to the user, before anything else.
\- If the project soul is not yet filled (you'll see a 'MANDATORY: Project soul is not yet filled' message), you MUST fill it before any other work:
  1\. Use `search_codebase` to explore the repo and infer project details.
  2\. Call `update_project_soul` with `context` and/or `conventions` params to populate the soul in one call.
  3\. If there is nothing to search, ask the user what the project is about, then call `update_project_soul`.
\- Skipping this call means you are working without context and will make wrong decisions.

### `update_project_soul` (~193 tokens)

\**UPDATE THE PROJECT SOUL** — write project context and/or conventions in a single call.
\- The project soul consists of `context.md` (goals, architecture, core features) and `conventions.md` (coding standards, agent norms).
\- Provide `context` to update `context.md`, `conventions` to update `conventions.md`, or both.
\- Use this when `get_project_soul` says the soul is unfilled, or whenever you need to update long-term project knowledge.
\- This replaces the file contents entirely (not append). For appending, use `update_context` instead.

Input parameters:

- `context` (string): Full content for context.md (project overview, architecture, core features, deployment). Omit to leave unchanged.
- `conventions` (string): Full content for conventions.md (language standards, styling, code patterns, agent norms). Omit to leave unchanged.

### `switch_project` (~93 tokens)

\**SWITCH PROJECT**: Rebind the live MCP session to another workspace without reconnecting.
\- Use this when you move from one repository to another inside the same client session.
\- If `projectRoot` is omitted, the server re-detects from the current runtime hints.

Input parameters:

- `projectName` (string): Optional explicit project name override.
- `projectRoot` (string): Absolute path to the target repository root.

### `post_job` (~139 tokens)

\**CREATE TICKET**: Post a new task to the Job Board.
\- Call this IMMEDIATELY when you receive a non-trivial task (2+ files, new features, refactors). Do not wait to be asked.
\- Break work into trackable jobs BEFORE you start coding.
\- Supports `dependencies` (list of other Job IDs that must be done first).
\- Priority: low, medium, high, critical.

Input parameters:

- `dependencies` (array): Array of Job IDs that must be completed before this job can be claimed.
- `description` (string, required)
- `priority` (string)
- `title` (string, required)

### `list_jobs` (~66 tokens)

\**INSPECT THE JOB BOARD**: Return all current jobs with status, priority, owner, dependencies, and timestamps.
\- Use before dividing work across agents or when you need to claim a specific ticket.

Input parameters:

- `includeCompleted` (boolean): Include done and cancelled jobs. Default: false.

### `cancel_job` (~50 tokens)

\**KILL TICKET**: Cancel a job that is no longer needed.
\- Requires `jobId` and a `reason`.

Input parameters:

- `jobId` (string, required)
- `reason` (string, required)

### `release_job` (~138 tokens)

\**RELEASE TICKET**: Put an abandoned in_progress job back on the board without cancelling it.
\- Use when another agent claimed a job and went silent — the job returns to 'todo' so anyone can pick it up.
\- Guarded: refuses if the assigned agent still looks active; pass `force: true` to override deliberately.
\- Parity with the hosted release_job tool.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity; recorded as the releaser.
- `force` (boolean): Release even if the assigned agent looks active. Default: false.
- `jobId` (string, required)

### `get_shared_context` (~83 tokens)

\**READ THE LIVE NOTEPAD**: Return the current shared notepad for this project — the team's short-term working memory (claims, decisions, blockers, handoffs).
\- Use to catch up on what other agents did without waiting for the ambient team-activity trailer.
\- Same shape as the hosted get_shared_context tool: { notepad, projectName }.

### `force_unlock` (~65 tokens)

\**ADMIN OVERRIDE**: Break a file lock.
\- **WARNING**: Only use this if a lock is clearly stale or the locking agent has crashed.
\- Will forcibly remove the lock from the database.

Input parameters:

- `filePath` (string, required)
- `reason` (string, required)

### `claim_next_job` (~117 tokens)

\**CLAIM WORK**: Claim the next job from the Job Board before starting it.
\- You MUST claim a job before editing files for that job.
\- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).
\- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.
\- Call this immediately after posting jobs, and again after completing each job to pick up the next one.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.

### `claim_job` (~88 tokens)

\**CLAIM A SPECIFIC TICKET**: Atomically claim a known job by ID.
\- Prefer this over `claim_next_job` when work has been intentionally assigned or agents have disjoint scopes.
\- Rejects completed, already claimed, or dependency-blocked jobs.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `jobId` (string, required)

### `complete_job` (~172 tokens)

\**CLOSE TICKET**: Mark a job as done and release file locks.
\- Call this IMMEDIATELY after finishing each job — do not accumulate completed-but-unclosed jobs.
\- Requires `outcome` (what was done).
\- If you are not the assigned agent, you must provide the `completionKey`.
\- **This is the primary way to release file locks.** Leaving jobs open holds locks and blocks other agents.
\- REMINDER: After completing all jobs, you MUST also call `finalize_session` to clear any remaining locks.

Input parameters:

- `agentId` (string): Optional — defaults to this session's unique identity.
- `completionKey` (string): Optional key to authorize completion if not the assigned agent.
- `jobId` (string, required)
- `outcome` (string, required)

### `index_file` (~150 tokens)

\**UPDATE SEARCH INDEX**: Add or refresh a single file in the RAG vector database.
\- Call this immediately after creating a new file or significantly refactoring an existing one — keeps `search_codebase` results fresh.
\- Only `filePath` is required. If you omit `content`, the server reads the file from disk itself — preferred, since it avoids round-tripping large file bodies through the tool call.
\- Pass `content` explicitly only when indexing material that doesn't live on disk (e.g. in-memory generated source).

Input parameters:

- `content` (string): Optional. Omit to have the server read filePath from disk.
- `filePath` (string, required): Absolute or project-relative path.

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server#diagnostics

## Score history

- 2026-08-03: 23

## Links

- npm package: https://www.npmjs.com/package/@virsanghavi/axis-server
- Socket report: https://socket.dev/npm/package/@virsanghavi/axis-server
- Repository: https://github.com/VirSanghavi/axis
- Website: https://useaxis.dev/
- Changelog RSS feed: https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server/changelog.json
- HTML version of this page: https://verifymcp.io/servers/dev-useaxis-axis/virsanghavi-axis-server