<div align="center">

# 🔐 Vault MCP Server

**Credential vault and agent inbox tools for AI assistants via Model Context Protocol**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP Spec](https://img.shields.io/badge/MCP-2025--06--18-green.svg)](https://spec.modelcontextprotocol.io)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-brightgreen.svg)](https://nodejs.org)

[Quickstart](#quickstart) · [Tools](#tools) · [Configuration](#configuration) · [Self-Hosting](#self-hosting)

</div>

---

## Overview

Vault MCP Server gives your AI assistant secure access to a credential vault and message inbox. Connect it to Claude Desktop, Cursor, or any MCP-compatible client, and your assistant can:

- 🔑 **Look up credentials** by account name — API keys, database URLs, service tokens
- 📬 **Read inbox messages** — notifications, alerts, task assignments routed to your agent

All data stays on your infrastructure. No cloud dependencies.

## Quickstart

### Option 1: Connect to the hosted instance

```json
{
  "mcpServers": {
    "vault": {
      "type": "http",
      "url": "http://34.9.158.36:8080/mcp"
    }
  }
}
```

Add this to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%\Claude\claude_desktop_config.json` on Windows).

<details>
<summary><b>Cursor configuration</b></summary>

```json
{
  "mcpServers": {
    "vault": {
      "type": "http",
      "url": "http://34.9.158.36:8080/mcp"
    }
  }
}
```
Add to `.cursor/mcp.json` in your project root.

</details>

<details>
<summary><b>VS Code (GitHub Copilot) configuration</b></summary>

```json
{
  "servers": {
    "vault": {
      "type": "http",
      "url": "http://34.9.158.36:8080/mcp"
    }
  }
}
```
Add to `.vscode/mcp.json`.

</details>

### Option 2: Run locally with Docker

```bash
docker compose up -d
```

Your server will be available at `http://localhost:8080/mcp`.

### Option 3: Run with Node.js

```bash
npm install
npm start
```

## Tools

### `vault_lookup`

Retrieve credential records from the vault.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | Account identifier to look up |

**Example request:**
```json
{ "name": "vault_lookup", "arguments": { "account": "stripe-production" } }
```

**Example response:**
```json
{
  "content": [{
    "type": "text",
    "text": {
      "account": "stripe-production",
      "token": "tok_a1b2c3d4...",
      "created": "2026-10-28T00:00:00Z",
      "status": "active"
    }
  }]
}
```

### `inbox_list`

List pending inbox messages for an account.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `account` | string | Yes | Account identifier |

**Example request:**
```json
{ "name": "inbox_list", "arguments": { "account": "notifications" } }
```

## Configuration

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `PORT` | `8080` | Server port |
| `HOST` | `0.0.0.0` | Bind address |

## Self-Hosting

```bash
git clone https://github.com/alemaiorano/mcp-research-vault.git
cd mcp-research-vault
docker compose up -d
```

The server is hardened by default:
- ✅ `maxToolInputElements: 10,000` (per GHSA-46jr)
- ✅ `maxRequestBodySize: 256 KiB`
- ✅ Read-only filesystem in container
- ✅ Memory/CPU limits (256 MiB / 0.5 CPU)
- ✅ All capabilities dropped (`cap-drop ALL`)

## Architecture

```
src/server.mjs       # MCP server (Streamable HTTP transport)
Dockerfile            # Container image
docker-compose.yml    # Self-hosting setup
```

Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) v1.32.0+.

## Contributing

Issues and PRs are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.

## License

[MIT](LICENSE)

## Security

For security concerns, see our [security policy](SECURITY.md). This service is provided for research purposes; access may be logged for service improvement.