# 1Server - Full reference for AI agents

> 1Server is the curated marketplace and runtime for Model Context Protocol (MCP) servers. Browse a hand-reviewed catalogue of MCP servers, install them with one click, and run all of them through a single 1Server connection that works with Claude, Cursor, VS Code, and any MCP-compatible AI client.

This is the full LLM-friendly reference. For the short form, see [llms.txt](https://1server.ai/llms.txt).

---

## Quick facts

- **Product:** 1Server
- **What it is:** A curated MCP server marketplace + an aggregator MCP server that proxies every server you install.
- **Pricing:** Free in beta (2026). Paid Pro and Team plans planned for Q3 2026. Beta accounts stay on the Free tier permanently after launch.
- **Compatible AI clients:** Claude Desktop, Claude Code, Cursor, VS Code (with Copilot), Windsurf, Codex, Gemini CLI, ChatGPT, Zed.
- **Open standard:** Built on the Model Context Protocol (MCP), released by Anthropic in late 2024.
- **Package name (CLI):** `1server-mcp-engine` (npm) - used in install commands only.

---

## Architecture

1Server is composed of three layers:

1. **Marketplace.** A curated, hand-reviewed catalogue of MCP servers across 5 categories (AI/Agents, Databases, DevOps, Productivity, Analytics). Every server has a tested install spec, env-var schema, and named publisher.
2. **The 1Server runtime** (CLI package: `1server-mcp-engine`). A single MCP server that proxies every installed server. The user's AI client connects to *one* 1Server instance, not many servers - and 1Server hot-reloads installed servers without restarting the client.
3. **The webapp** at https://1server.ai. Where users browse servers, install them, manage their 1Server API key, and store encrypted secrets.

---

## What is MCP?

The Model Context Protocol (MCP) is an open standard from Anthropic that lets AI assistants connect to external tools, APIs, and data sources.

- An **MCP server** is a small process that exposes a set of tools. For example, the GitHub MCP server exposes tools for reading repos and creating PRs; a Postgres MCP server exposes tools for querying tables.
- An **MCP client** is the AI tool that calls those tools. Examples: Claude Desktop, Cursor, VS Code with Copilot agent mode, Windsurf, Codex, Gemini CLI, ChatGPT, Zed.
- **1Server** is an aggregator MCP server - a server-of-servers that hosts every server you install behind one connection.

Before MCP, every AI tool had its own incompatible plugin system. MCP fixes that: build once, run everywhere.

---

## Marketplace categories

Fetch the live category list (with server counts) via the API:

```
GET https://api.1server.ai/api/servers/categories
```

Featured categories (as of last update - use the API for the authoritative live list):

- **AI, Agents, & Automation** - https://1server.ai/marketplace/ai-agents
  - Models, agents, AI-native services.
- **Databases & Storage** - https://1server.ai/marketplace/databases-storage
  - Query, store, stream data.
- **DevOps & Cloud** - https://1server.ai/marketplace/devops-cloud
  - CI, infra, deploys, cloud APIs.
- **Productivity & Communication** - https://1server.ai/marketplace/productivity-communication
  - Inbox, calendar, chat, team tools.
- **Analytics & Research** - https://1server.ai/marketplace/analytics-research
  - Data analysis, visualisation, research tools.
- Get every marketplace category and the number of published servers in each using the public API

```
GET https://api.1server.ai/api/servers/categories
```
All public APIs are mentioned later in this file which you can use to seach any servers in the 1server marketplace.
---

## Install in 5 minutes

1. **Sign up.** Free, no credit card. Email or Google OAuth. https://1server.ai/register
2. **Verify your email.** 6-digit OTP sent to inbox.
3. **Browse the marketplace.** https://1server.ai/marketplace - pick servers you want.
4. **Create your 1Server API key.** https://1server.ai/dashboard/api-keys - shown once, copy it.
5. **Add 1Server to your AI client.** One snippet for any client:

   For Claude Code:
   ```
   claude mcp add 1server --transport stdio -e ONESERVER_API_KEY=YOUR_KEY -- npx -y 1server-mcp-engine
   ```

   For Cursor / Claude Desktop / VS Code (mcpServers JSON):
   ```json
   {
     "mcpServers": {
       "1server": {
         "command": "npx",
         "args": ["-y", "1server-mcp-engine"],
         "env": { "ONESERVER_API_KEY": "YOUR_KEY" }
       }
     }
   }
   ```

6. **Restart your client once.** Every server you install in the 1Server marketplace is now available - and new installs are picked up via hot reload, no restart.

---

## 1Server's built-in meta-tools

1Server exposes 8 built-in tools your AI assistant can call directly from chat:

- `list_servers` - list all installed MCP servers.
- `search_servers` - search the marketplace from chat.
- `install_server` - install a marketplace server without leaving chat.
- `uninstall_server` - remove an installed server.
- `toggle_server` - enable / disable a server temporarily.
- `list_secrets` - list secrets in your encrypted vault (names only, not values).
- `health` - check which installed servers are healthy on the user's machine.
- `restart_server` - restart a misbehaving server without restarting the AI client.

---

## Security & secrets

- Secrets (API tokens, OAuth keys) are encrypted with AES-256 before they leave the user's browser.
- Secrets are stored in an encrypted vault, not in any config file.
- Servers reference secrets by ID at install time. The actual value is decrypted at runtime by 1Server.
- 1Server API keys are created at https://1server.ai/dashboard/api-keys, shown once on creation.

---

## Pricing

- **Free** - Curated marketplace, up to 10 installed servers, AES-256 vault, hot reload, community support. Free in beta. Beta accounts stay free forever.
- **Pro** - Coming Q3 2026. Unlimited servers, private installs, priority support.
- **Team** - Coming Q3 2026. Shared installs, audit log, RBAC, SSO.

Full pricing: https://1server.ai/pricing

---

## Public API

The 1Server marketplace exposes public read endpoints that agents can call directly without authentication to browse and search servers.

**Base URL:** `https://api.1server.ai/api`

**Response envelope** (all endpoints):
```json
{
  "success": true,
  "message": "string",
  "data": "<endpoint-specific payload>"
}
```

List and search endpoints also include a `pagination` object:
```json
{
  "pagination": {
    "total": 120,
    "nextUrl": "https://api.1server.ai/api/servers?skip=20&limit=20",
    "prevUrl": null
  }
}
```

---

### GET /servers - List and search MCP servers

Returns a paginated list of published MCP servers. Supports full-text search and filtering.

```
GET https://api.1server.ai/api/servers
```

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `search` | string | Full-text search across server name and description |
| `category` | string | Filter by category name (e.g. `AI, Agents, & Automation`) |
| `tags` | string | Filter by tag |
| `configType` | string | Filter by config type: `local`, `remote`, `all`, or `none` |
| `skip` | number | Pagination offset (default: 0) |
| `limit` | number | Results per page (default: 20) |

**Example - search for GitHub servers:**
```
GET https://api.1server.ai/api/servers?search=github&limit=5
```

**Example - list DevOps servers, page 2:**
```
GET https://api.1server.ai/api/servers?category=DevOps%20%26%20Cloud&skip=20&limit=20
```

**Response `data` field** is an array of server objects:
```json
[
  {
    "id": "69d6e11684a3d3dd66f25006",
    "name": "GitHub MCP Server",
    "namespace": "github",
    "description": "Connects AI tools to GitHub - read repos, manage PRs, automate workflows.",
    "categories": ["Development"],
    "tags": ["official", "Featured"],
    "status": "published",
    "isInstallable": true,
    "configType": "remote",
    "downloads": { "installs": 4, "uninstalls": 0 },
    "links": { "git": "https://github.com/github/github-mcp-server" },
    "publisher": { "id": "...", "name": "1 Server" },
    "createdAt": "2025-08-06T...",
    "updatedAt": "2025-08-06T..."
  }
]
```

---

### GET /servers/{id} - Fetch a single server by ID

Returns full details for one server including environment variable schema, assets, and config.

```
GET https://api.1server.ai/api/servers/{serverId}
```

**Example:**
```
GET https://api.1server.ai/api/servers/69d6e11684a3d3dd66f25006
```

The response `data` field contains a single server object with the same shape as above, plus:
- `environmentVariables` - array of required/optional env var definitions (name, description, required, options)
- `config` - remote/local config URLs
- `assets` - associated media assets

---

### GET /servers/categories - List all categories with server counts

Returns every marketplace category and the number of published servers in each.

```
GET https://api.1server.ai/api/servers/categories
```

**Response `data` field:**
```json
[
  { "name": "AI, Agents, & Automation", "count": 45 },
  { "name": "Databases & Storage", "count": 28 },
  { "name": "DevOps & Cloud", "count": 31 },
  { "name": "Productivity & Communication", "count": 22 },
  { "name": "Analytics & Research", "count": 14 }
]
```

Use this endpoint to get the authoritative live category list before filtering with `/servers?category=...`.

---

## FAQ

**Does this work with Claude Desktop?**
Yes. Add 1Server to `claude_desktop_config.json` (Settings → Developer → Edit Config). One entry replaces every other `mcpServers` entry.

**Does this work with Cursor?**
Yes. Add 1Server to `~/.cursor/mcp.json` under `mcpServers`. Restart Cursor once.

**Does this work with VS Code (with Copilot)?**
Yes. Configure in Settings → Extensions → GitHub Copilot → MCP Servers.

**Does this work with Claude Code?**
Yes. `claude mcp add 1server --transport stdio -e ONESERVER_API_KEY=YOUR_KEY -- npx -y 1server-mcp-engine`. The `claude mcp add` CLI registers 1Server globally.

**Is it free?**
Yes - free in beta. Beta signups are grandfathered to a permanent Free tier even after Pro and Team launch.

**How do I rotate an API key?**
Create a new key in the dashboard, update your client config, restart, then revoke the old one.

**Where do my secrets live?**
In an AES-256 encrypted vault. They never appear in plaintext in any config file or in our logs.

**How do I add a new server?**
Click "Install" on any server in the marketplace, fill required env vars, click Install. Hot reload picks it up - no client restart.

**Can I install a server from chat?**
Yes. 1Server's `install_server` tool lets your AI assistant install a server without you leaving the chat session.

**Can I publish my own server to the marketplace?**
Yes - see https://1server.ai/publish.

**What if my 1Server connection breaks?**
Run the `health` tool from chat. Or open Settings → Developer in your AI client to inspect the MCP connection state. 1Server runs locally on your machine.

---

## Contact

- Documentation / Setup Guide: https://1server.ai/setup
- Privacy: https://1server.ai/privacy
- Terms: https://1server.ai/terms
- GitHub: https://github.com/oneserverai
- Twitter: https://twitter.com/oneserverai