# Contextium MCP Server

[![npm version](https://img.shields.io/npm/v/@contextium/mcp-server.svg)](https://www.npmjs.com/package/@contextium/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Give your AI assistant persistent, searchable access to your team's docs, SOPs, coding standards, and agent configs — no copy-pasting.**

Contextium is a central knowledge store that AI assistants can read directly via MCP. Connect Claude, Cursor, Windsurf, or any MCP-compatible client and your AI will automatically follow your team's guidelines, load the right context for each task, and stay consistent across every session.

![Contextium MCP — loading a workflow in Claude](./docs/screenshot-workflow.png)

---

## Why Contextium?

Without a shared knowledge store, every AI session starts from scratch. You paste in the same coding standards, re-explain the same architecture, and hope the AI stays consistent. Contextium solves this at the source.

- **Context libraries** — store SOPs, coding standards, architecture docs, and API references
- **Agents** — pre-configured AI personas with skills and constraints baked in
- **Skills** — reusable knowledge modules the AI can load on demand
- **Workflows** — named context sets that load everything needed for a task in one command
- **Marketplace** — install community-built agents and skills instantly

Once connected, Claude pulls in your team's knowledge automatically. You stop repeating yourself.

---

## Quick Start — Remote MCP (Recommended)

No installation required. Add the hosted Contextium MCP server to your AI client and authenticate once.

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "contextium": {
      "type": "sse",
      "url": "https://mcp.contextium.io/sse"
    }
  }
}
```

Restart Claude Desktop. A browser window will open on first use to authenticate your Contextium account.

### Claude Code (CLI)

```bash
claude mcp add contextium --transport sse https://mcp.contextium.io/sse
```

### Cursor

```json
{
  "mcpServers": {
    "contextium": {
      "url": "https://mcp.contextium.io/sse"
    }
  }
}
```

### VS Code (Copilot)

```json
{
  "mcp": {
    "servers": {
      "contextium": {
        "type": "sse",
        "url": "https://mcp.contextium.io/sse"
      }
    }
  }
}
```

---

## Option 2: Local MCP (Self-hosted)

Run the MCP server locally via npm for offline access or self-hosting.

```bash
# Authenticate and configure
npx @contextium/mcp-server@latest setup
```

Then add to your Claude Desktop config:

```json
{
  "mcpServers": {
    "contextium": {
      "command": "npx",
      "args": ["-y", "@contextium/mcp-server@latest"]
    }
  }
}
```

### Auth commands

```bash
npx @contextium/mcp-server setup      # Initial setup — opens browser to authorize
npx @contextium/mcp-server status     # Check connection and active workspace
npx @contextium/mcp-server profiles   # Manage multiple accounts
npx @contextium/mcp-server logout     # Sign out
```

---

## What Claude Can Do

Once connected, you interact naturally — Contextium handles the context loading:

```
"Load our React coding standards and review this component for compliance"

"What are our team's rules for writing API endpoints?"

"Load the Backend workflow and help me scaffold a new service"

"Find all documentation related to our authentication flow"

"Install the code-reviewer agent from the marketplace"

"Notify the team about this new spec I just created"

"Notify Sarah about this workflow — just her, not everyone"
```

![Contextium MCP — searching documentation in Claude](./docs/screenshot-search.png)

---

## MCP Tools

Tags in Contextium are flat and untyped — a tag is just a `#value`, with no categories or `type:value` format. A tag is **created by adding a `#value` token to a file's content** — either edit the file directly, or use `manage_relationship` (`type=tag`, `action=add|remove`), which tags a file by editing its content and auto-creates the tag on save. `list_tags` lists workspace tags. There is no separate create-a-tag tool.

### Read
| Tool | Description |
|------|-------------|
| `list_context_libraries` | List documentation projects |
| `list_agents` | List AI agent configurations |
| `list_skills` | List skills library |
| `list_files` | List files in a library, agent, or skill |
| `get_file` | Get file content and metadata |
| `get_file_versions` | View version history |
| `get_context_library_structure` | Get full folder structure |
| `search_documentation` | Full-text search across all docs |
| `search_by_tags` | Find files matching tags |
| `list_workflows` | List available workflows |
| `load_workflow` | Load all files tagged in a workflow |
| `list_tags` | List all flat workspace tags |
| `list_workspaces` | List accessible workspaces |
| `get_agent` | Get agent configuration |
| `get_skill` | Get skill content |
| `get_workflow` | Get workflow details |
| `get_context_library` | Get library details |

### Write
| Tool | Description |
|------|-------------|
| `create_file` | Create a new file |
| `update_file` | Update an existing file |
| `delete_file` | Delete a file |
| `create_context_library` | Create a new library |
| `create_agent` | Create an agent configuration |
| `create_skill` | Create a new skill |
| `create_workflow` | Create a workflow |
| `update_workflow` | Update a workflow |
| `update_agent` | Update an agent |
| `manage_relationship` | Add or remove a `tag` on a file by editing the file content (inline `#value`) — auto-creates the tag on save |
| `add_skill_to_agent` | Associate a skill with an agent |
| `remove_skill_from_agent` | Remove a skill from an agent |

### Marketplace
| Tool | Description |
|------|-------------|
| `search_marketplace` | Search the Contextium Marketplace |
| `get_marketplace_listing` | Get marketplace item details |
| `install_marketplace_listing` | Install a marketplace agent or skill |

### Team
| Tool | Description |
|------|-------------|
| `notify_team_members` | Notify workspace team members about a file, workflow, agent, or library. Target everyone, or specific members by name, email, or ID. Respects each member's notification preferences and Do Not Disturb settings. |

---

## Troubleshooting

**OAuth login not appearing (Remote MCP)**
Ensure your client supports remote MCP with OAuth: Claude Desktop 0.7+, Cursor 0.42+. Restart after updating config.

**"Not authenticated" error (Local MCP)**
```bash
npx @contextium/mcp-server status
npx @contextium/mcp-server setup
```

**Claude Desktop not seeing tools**
1. Check config file syntax (valid JSON, correct path)
2. Ensure `npx` is in your PATH
3. Restart Claude Desktop completely
4. Check logs: `~/Library/Logs/Claude/mcp*.log`

**API timeout**
Check [https://status.contextium.io](https://status.contextium.io) or verify your token with `npx @contextium/mcp-server status`.

---

## Links

- **Website**: https://contextium.io
- **Documentation**: https://contextium.io/docs/mcp-integration
- **Remote MCP**: https://mcp.contextium.io
- **GitHub**: https://github.com/contextium-io/contextium
- **Support**: support@contextium.io

## License

MIT © Contextium

---

Built with [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic