> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toolshed.philo.ventures/llms.txt
> Use this file to discover all available pages before exploring further.

# Server API Overview

> The Toolshed REST API — auth, connections, tokens, registry, policy, audit, and elicitation.

The Toolshed API server is built with [Hono](https://hono.dev/) and uses [Better Auth](https://better-auth.com) for authentication. All endpoints are under the `/api` base path.

## Authentication

Routes are protected by one of two mechanisms:

1. **Better Auth session cookie** — set automatically by the web app after login
2. **Bearer token** — `Authorization: Bearer <TOOLSHED_API_SECRET>` for CLI and programmatic access

**Unauthenticated routes:**

* `GET /api/health`
* `GET|POST /api/auth/*` (handled by Better Auth)
* `ALL /api/mcp/:token` (authenticates via the MCP token in the URL — see [MCP Server Overview](/mcp/overview))

## Route groups

| Group                              | Path prefix        | Description                                                                                         | Status      |
| ---------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------- | ----------- |
| [Auth](/server/auth)               | `/api/auth`        | Better Auth (login, OAuth social + genericOAuth, sessions)                                          | Implemented |
| [Connections](/server/connections) | `/api/connections` | Tool connections with encrypted secrets, MCP endpoints                                              | Implemented |
| [Connectors](/server/connectors)   | `/api/connectors`  | Connector availability registry (which providers have creds)                                        | Implemented |
| [Tokens](/server/tokens)           | `/api/tokens`      | OAuth token vending + three-source `resolveToken()`                                                 | Implemented |
| Remote MCP                         | `/api/mcp/:token`  | HTTP MCP transport (`StreamableHTTPTransport` from `@hono/mcp`) — see [MCP Overview](/mcp/overview) | Implemented |
| [Registry](/server/registry)       | `/api/registry`    | Tool catalog, source registration, search                                                           | Implemented |
| [Policy](/server/policy)           | `/api/policy`      | Role management and access resolution                                                               | Stub        |
| [Audit](/server/audit)             | `/api/audit`       | Audit trail for tool invocations                                                                    | Stub        |
| [Elicitation](/server/elicitation) | `/api/elicitation` | Pending approval storage and resolution                                                             | Stub        |

## Health check

```
GET /api/health
→ { "ok": true }
```

## Local development

```bash theme={null}
# Copy env template and fill in credentials
cp apps/server/.env.example apps/server/.env.local

# Start the dev server (loads .env.local automatically)
pnpm --filter @toolshed/server dev
```

The server runs at `http://localhost:3000` by default.