# Connect Server Agent to your MCP client

The Server Agent becomes a **tool provider** for any MCP-compatible client —
Claude Desktop, Claude Code, Cursor, Cline, Zed, and others. Inference runs
through whatever AI subscription your client uses, so you don't burn extra
API credits just to use the agent.

> **No subscription? No problem.** The agent also ships with a built-in chat
> panel that takes any API key from Anthropic, OpenAI, xAI, or Google. Use it
> directly from the web admin without a desktop client.

---

## Prerequisites

- Server Agent installed and reachable at `https://your-domain.com/`
- An admin account on the agent (the password you set during install)
- An MCP-compatible client installed locally
- **HTTPS required** for non-localhost installs. Most clients refuse `http://`
  for remote servers; use Let's Encrypt or Cloudflare for a free cert.

---

## The 30-second connection (recommended)

Server Agent ships with a built-in **OAuth 2.1 authorization server**, so any
modern MCP client can connect to it the same way it connects to a hosted
service like Notion or Linear. No tokens, no JSON files, no restarts.

### Step 1 — Get your MCP URL

1. Open the agent admin panel → **Settings** → **MCP**
2. Copy the URL shown at the top (e.g. `https://ai.example.com/mcp.php`)

### Step 2 — Paste it into your client

Pick your client below. The same URL works in all of them.

| Client | Where to paste |
|---|---|
| **Claude Desktop** (chat or Code mode) | Settings → **Connectors** → **Add custom connector** → paste URL |
| **Cursor** | Settings → **MCP** → **Add new MCP server** → paste URL |
| **Cline** (VSCode) | Cline Settings → **MCP Servers** → **Add server** → paste URL |
| **Zed** | Settings → **Context servers** → paste URL |
| **Continue** | Settings → MCP → paste URL |

> **The Custom Connector dialog might ask for OAuth Client ID / Secret. Leave
> them blank.** This server uses Dynamic Client Registration — your client
> registers itself automatically.

### Step 3 — Approve in your browser

Your client will open a browser tab pointing at this Server Agent. You'll see:

1. The agent's login page (one-time per browser) — sign in with your admin password
2. A consent screen: *"Authorize \[client name\] to access this Server Agent?"* with the list of permissions
3. Click **Allow**

The browser tab closes itself, and your client is now connected with all 32
tools available. Total elapsed time: ~30 seconds.

### Step 4 — Try a tool

Ask your AI client naturally:

> *"Use server-agent to check git status on my server"*

It'll call the `git_status` tool and show the output. You're done.

---

## How OAuth tokens work here

- Access tokens are short-lived (1 hour) and auto-refresh via the
  refresh-token grant — your client handles this transparently
- Refresh tokens last 30 days; using one rotates it (replay-detection built in)
- Your password never leaves this server. Clients only ever see access tokens.
- **Revoke any time:** Settings → MCP → Authorized clients → **Revoke**.
  Cuts that client off immediately, doesn't affect any other connected clients.

---

## Advanced: manual token connection

For CI scripts, automation, OAuth-incompatible clients, or quick testing,
you can also use the legacy bearer-token flow.

### When to use this

| Scenario | Use OAuth | Use manual token |
|---|---|---|
| Connecting a desktop AI client (Claude/Cursor/Cline/Zed) | ✅ | only if OAuth fails |
| GitHub Actions / CI/CD pipeline | | ✅ |
| Custom script calling tools via curl | | ✅ |
| Embedded device with no browser | | ✅ |
| Your client doesn't support OAuth yet | | ✅ |

### Generate a token

1. Settings → **MCP** → expand **Advanced: manual token connection**
2. Click **Generate MCP Token**
3. The panel auto-shows the right config snippet for whichever client you pick
4. Copy and paste per the per-client instructions below

Tokens last 90 days. Generate a fresh one any time; revoke old ones from the
same panel.

### Per-client manual setup

#### Claude Desktop (chat or Code mode)

The OAuth path above is what you want. If you really need manual tokens,
open `claude_desktop_config.json`:

- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Paste this (the agent's panel will hand you the populated version):

```json
{
  "mcpServers": {
    "server-agent": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://your-domain.com/mcp.php",
        "--header", "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}
```

This routes through `mcp-remote`, a local proxy that bridges Claude Desktop's
stdio transport to the bearer-token HTTP endpoint. Requires Node.js. Restart
Claude Desktop fully (Tray → Quit, not just close window).

#### Claude Code

Use the CLI command:
```bash
claude mcp add --transport http server-agent https://your-domain.com/mcp.php \
  --header "Authorization: Bearer YOUR_TOKEN"
```

Or edit `~/.claude.json` directly:

```json
{
  "mcpServers": {
    "server-agent": {
      "type": "http",
      "url": "https://your-domain.com/mcp.php",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

In any session, run `/mcp` to verify.

#### Cursor

Edit `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "server-agent": {
      "type": "http",
      "url": "https://your-domain.com/mcp.php",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}
```

Settings → MCP → Reload `server-agent`.

#### Cline / Zed / Continue / generic

Standard MCP HTTP transport JSON; adapt the file location and outer key per
your client's docs:

```json
"server-agent": {
  "type": "http",
  "url": "https://your-domain.com/mcp.php",
  "headers": { "Authorization": "Bearer YOUR_TOKEN" }
}
```

Outer keys per client: `mcpServers` (most), `context_servers` (Zed).

---

## What tools become available?

| Category | Tools |
|---|---|
| **Shell / files** | `bash_execute`, `file_read`, `file_write`, `file_browse`, `file_search` |
| **Git / deploy** | `git_status`, `git_log`, `git_diff`, `deploy_log_recent` |
| **Database** | `db_query` |
| **Services** | `service_control`, `process_list`, `health_check` |
| **DevOps** | `ssl_check`, `dns_lookup`, `logs_list`, `log_tail`, `cron_list`, `disk_analyze`, `htaccess_audit` |
| **Safety** | `backup_create`, `backup_list`, `rollback_list`, `rollback_restore` |
| **Env mgmt** | `envs_list`, `envs_switch` |
| **Memory** | `knowledge_get`, `knowledge_save`, `project_profile`, `session_history` |
| **Meta** | `host_capabilities`, `workspaces_list` |

A valid license is required to expose any tools. Tier sets seat count
(servers) and white-label access:

- **Starter** ($29): 1 server · all 32 tools · unlimited team users
- **Pro** ($79): up to 5 servers · hub-mode multi-server control · all 32 tools
- **Agency** ($199): unlimited servers · **white-label branding** · all 32 tools

---

## First things to ask your AI

Once connected, try these prompts from your MCP client:

- *"Use the server agent to check what's running on my production server"*
- *"Tail the last 100 lines of error.log and summarize the issues"*
- *"Check SSL cert expiry on my-domain.com and tell me if anything's expiring soon"*
- *"Run a disk usage audit and show me the biggest directories"*
- *"Back up the current codebase, then git pull and run migrations"*
- *"Save a knowledge entry that the staging DB uses port 3307"*

The AI picks the right tool, calls it, and responds with the result — same
conversation, no context switching.

---

## Troubleshooting

### OAuth: "Couldn't reach the MCP server"

The client tried to fetch `/.well-known/oauth-protected-resource` and got a
404 instead of metadata. Causes:

- The `.htaccess` rewrite for `.well-known/*` URLs isn't being applied. On
  Apache: ensure `AllowOverride All` for the install directory. On nginx:
  add the rewrite rule from `install.php`'s output (shown after install)
- The web server is blocking dot-prefixed paths. Some shared hosts deny
  `.well-known/*` by default — contact your host or move to a VPS.
- **Quick test from any terminal:** `curl https://your-domain.com/.well-known/oauth-protected-resource` should return JSON, not HTML.

### OAuth: "Admin access required"

Only admin-role users can authorize MCP clients. If you logged in with a
non-admin account, log out (link at the bottom of the consent page) and log
back in as the admin.

### OAuth: stuck on the login screen

The server cookie isn't being set. Two common causes:

- You're on `http://` and the cookie has `Secure` set — switch to HTTPS
- Your browser is blocking third-party cookies — your client opens the OAuth
  page in a new browser session that may not share cookies. Disable
  third-party cookie blocking for your agent's domain, or complete the OAuth
  flow in your default browser instead

### Manual token: 401 Unauthorized

- Token expired (90 days for manual tokens) — generate a new one
- Token was revoked from the panel
- You pasted only part of the token — regenerate, copy the full hex string

### Manual token: "shell_exec is disabled"

Your host has `shell_exec` disabled (common on shared cPanel). Run
`host_capabilities` via your MCP client to see which tools work; contact
your host to enable, or upgrade to a VPS.

### Tools appear but fail with permission errors

The user that authorized the OAuth flow (or whose token you used) was a
viewer/developer rather than admin. Some tools need admin role; some need
root on the server (`service_control`, `cron_*`).

### HTTPS certificate errors

Most MCP clients reject self-signed certs. Use Let's Encrypt (free) or
Cloudflare. Test your chain at https://www.ssllabs.com/ssltest/.

---

## Security notes

- The agent enforces the **same role permissions** for OAuth and manual
  tokens as for web sessions. A viewer-scope token can't call
  `bash_execute` or `db_query` destructively.
- All tool calls are logged to `logs/agent.log` with the token hint and
  client/user identification.
- Use IP allowlist (Settings → Security) to restrict MCP access to specific
  office IPs or your home IP.
- Keep your Server Agent behind HTTPS. Anyone who completes the OAuth flow
  has the permissions of the user who authorized it.
- OAuth refresh tokens implement reuse detection: if an attacker steals a
  refresh token, the next legitimate refresh invalidates the entire chain.