Work With Alloy

by Alloy-Systems

243 downloads
Not rated
GitHub

About

Alloy is an AI-native workspace where teams and AI agents share knowledge, artifacts, workflows, and controlled access to external systems through one common operating layer.

Details

Author
Alloy-Systems
Downloads
243
Categories
Other

Jump to

- Shared source-of-truth skill (work-with-alloy) for all agents.
- Read organizational knowledge before answering queries.
- Write durable artifacts back to Alloy (proposals, specs, logs).
- Access approved business systems through Alloy-controlled MCP.
- Coordinate multi-agent operations with task handoffs via MCP/API.
- Call Alloy cloud agents for delegated work from outputs.

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Work With Alloy
    Command (node, npx, python, etc.)

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

Install the plugin into Claude Code or Codex from the Alloy marketplace. Set the ALLOY_TOKEN environment variable in your host shell before starting the host. After installing, restart the host so the bundled MCP config is loaded. Verify installation with claude mcp list (expect plugin:work-with-alloy:alloy as connected). For Codex use codex plugin marketplace add Alloy-Systems/alloy-marketplace; for Claude Code use /plugin marketplace add Alloy-Systems/alloy-marketplace then /plugin install work-with-alloy@alloy-marketplace.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "work with alloy": {
            "alloy": {
                "type": "http",
                "url": "https://api.alloy.cx/mcp",
                "bearer_token_env_var": "ALLOY_TOKEN"
            }
        }
    }
}

McpServers

{
    "alloy": {
        "type": "http",
        "url": "https://api.alloy.cx/mcp",
        "bearer_token_env_var": "ALLOY_TOKEN"
    }
}

Work with Alloy

About Alloy

Alloy is an AI-native workspace where your team and AI agents collaborate — sharing artifacts, knowledge, skills, and access to external systems, all on one foundation. Connect Claude, Codex, or Gemini — or spawn Alloy cloud agents — and let them coordinate with each other and your teammates.

Start free at alloy.cx · Docs: alloy.cx/docs

---

This plugin teaches any AI agent to use Alloy as its source of truth and gives it reusable Alloy-specific operating skills — reading shared knowledge before answering, writing durable notes and artifacts, creating workflows, running operational reviews, and spawning autonomous agents.

The shared source of truth is the work-with-alloy skill. Platform-specific
plugin manifests are thin wrappers around the same skill content.

Use Cases

Use Alloy as an AI agent's shared operating layer for work with humans and other
agents, including Claude, Codex, Alloy cloud agents, and other AI
agents.

- Read shared organizational knowledge before answering: company docs,
decisions, knowledge notes, communication history, and context maintained by
all AI agents and humans.
- Write durable artifacts back to Alloy: proposals, research, summaries, specs,
logs, decisions, and reusable notes that future agents can pick up.
- Access approved business systems through Alloy-controlled MCP: the agent
connects once to Alloy, while Alloy governs which upstream MCPs, APIs, files,
secrets, and actions are available.
- Work across connected tools without each agent configuring every integration
separately: CRM, support, docs, calendars, email, databases, internal systems,
and private gateways.
- Call Alloy cloud AI agents for delegated work, then continue from their
outputs and artifacts.
- Create or configure Alloy AI teammates, skills, and workflows so repeatable
work becomes a governed organizational process.
- Coordinate multi-agent operations where AI agents hand off tasks through
MCP/API triggers.
- Keep organizational learning portable across agents: knowledge, artifacts,
access rules, and audit trail.

Layout

- skills/work-with-alloy/ - core source-of-truth skill.
- skills/review-alloy-operations/ - operational review skill for auditing teammates, workflows, MCPs, and recent activity.
- skills//references/ - supporting playbooks loaded by each skill.
- skills//agents/openai.yaml - Codex/OpenAI skill UI metadata.
- skills/work-with-alloy/assets/ - shared skill UI assets such as the Alloy icon.
- .codex-plugin/plugin.json - Codex plugin manifest.
- .claude-plugin/plugin.json - Claude Code plugin manifest.
- .mcp.json - Alloy hosted MCP configuration using ALLOY_TOKEN.

Shared Skill

The skills under skills/ are intended to stay host-neutral. Update the shared
skill content there instead of maintaining separate Claude and Codex instruction
trees.

Prerequisites

These apply to anyone installing the plugin into Claude Code or Codex.

1. ALLOY_TOKEN environment variable

The bundled .mcp.json reads the Alloy MCP bearer from ALLOY_TOKEN. Export
it in the host shell before starting Claude Code or Codex:

export ALLOY_TOKEN="<your-alloy-token>"

Get a token at https://alloy.cx/docs/reference/tech-docs/hosted-mcp.

2. Host restart after install

The plugin's MCP server is loaded by the host at startup. After installing or
updating the plugin, restart the host so it can load the bundled MCP config.

Codex

The Codex plugin manifest references ./skills/ and ./.mcp.json.

Set ALLOY_TOKEN in the host environment before using the bundled MCP config.

Marketplace registration and app-server install have been validated with Codex
0.125.0:

codex plugin marketplace add Alloy-Systems/alloy-marketplace

Codex installs work-with-alloy from the marketplace entry pointing at a tagged
release. After install, Codex reports the plugin as enabled and exposes the
work-with-alloy:work-with-alloy skill plus the bundled alloy MCP server.

Claude Code

The Claude plugin manifest at .claude-plugin/plugin.json references the same
./skills/ and ./.mcp.json as the Codex side. Install flow once the Alloy
marketplace is published:

/plugin marketplace add Alloy-Systems/alloy-marketplace
/plugin install work-with-alloy@alloy-marketplace

Claude Code's plugin installer clones plugin source from GitHub over SSH by
default. Before /plugin install, make sure one of these is true:

- A working GitHub SSH key on this machine (test: ssh -T git@github.com).
- A global git URL rewrite that pushes plugin clones through HTTPS:

  git config --global url."https://github.com/".insteadOf "git@github.com:"

Set ALLOY_TOKEN in the host environment before using the bundled MCP config.

After install, restart Claude Code and confirm registration:

claude mcp list   # expect plugin:work-with-alloy:alloy as connected

Versioning policy

This project follows semantic versioning with synchronized releases across
Claude Code and Codex wrappers. A single version applies to the whole release:
the shared skill content in skills/work-with-alloy/, both plugin.json
manifests, the .mcp.json config, and this README. Both
.codex-plugin/plugin.json and .claude-plugin/plugin.json always carry the
same version field.

Semver semantics for this plugin

| Bump | What it means | Examples |
|------|---------------|----------|
| Patch (0.1.0 → 0.1.1) | Cosmetic only. Typo, wording tweak, broken link, clarification. No change in how the agent behaves. | Fix a typo in SKILL.md. Update a stale URL in references/. |
| Minor (0.1.0 → 0.2.0) | Backward-compatible addition. New rule, new Quick Reference row, new reference playbook, new optional manifest field. Prior usage still works. | Add a new rule to Core rules. Add a new entry to a Quick Reference table. Add a new playbook under references/. |
| Major (0.x → 1.0, 1.x → 2.x) | Breaking change. A canonical path, file name, required field, or required rule changes in a way that prior consumers may break. | Rename Personal/<username>/.knowledge/knowledge.md to a different path. Remove a Core rule. Restructure references/ so existing links break. |

Pre-1.0 (0.x) signals "still stabilizing - minor bumps may include breaking
changes". The 1.0.0 line will be cut when the canonical paths and Core rules
are confirmed stable.

Release flow

1. Work happens on feature branches, merged into main via PR.
2. When main is in a state worth releasing, bump both
.codex-plugin/plugin.json and .claude-plugin/plugin.json version
fields in the same commit.
3. Cut a git tag on the merge commit: git tag vX.Y.Z && git push origin vX.Y.Z.
4. Bump the corresponding ref field in the Alloy-Systems/alloy-marketplace repo's
marketplace.json entry for work-with-alloy. Users receive the new
version through /plugin update only after this marketplace bump.
5. Untagged commits on main are visible to anyone reading the repo but are
not delivered through /plugin install or /plugin update until the
marketplace points at a new tag.

Cadence

Tags are cut per logical release, not on every commit. A typical trigger is a
new Core rule landing, a new reference playbook being added, or a breaking
restructure being completed and ready to ship. Cosmetic-only changes can
accumulate in main and be released as a patch bump when convenient.

License

Apache License 2.0.

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

{
    "mcpServers": {
        "work with alloy": {
            "alloy": {
                "type": "http",
                "url": "https://api.alloy.cx/mcp",
                "bearer_token_env_var": "ALLOY_TOKEN"
            }
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other

Reactive Resume

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

39.5k
Other