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

# Architecture

> How the SmartAlex MCP server connects your AI client to your workspace, over local stdio or the hosted cloud endpoint.

There are two ways to run the SmartAlex MCP server, and they connect to the same place: a tenant-scoped API gateway that fronts your workspace.

## Local vs cloud

```mermaid theme={null}
flowchart TB
    subgraph Local["Local (stdio)"]
      direction LR
      LC["AI client"] <-->|"stdio"| NP["@smartalex/mcp-server<br/>(npm, on your machine)"]
      NP <-->|"HTTPS + API key"| GW1["API gateway"]
    end
    subgraph Cloud["Cloud (hosted)"]
      direction LR
      CC["AI client"] <-->|"HTTPS + OAuth / API key"| HM["Hosted MCP server"]
      HM <-->|"internal"| GW2["API gateway"]
    end
    GW1 --> WS["Your workspace<br/>(tenant-scoped)"]
    GW2 --> WS
```

|                   | Local (stdio)                               | Cloud (hosted)                          |
| ----------------- | ------------------------------------------- | --------------------------------------- |
| Runs              | On your machine, via npm                    | On our infrastructure                   |
| Client talks over | stdio                                       | HTTPS                                   |
| Auth              | API key                                     | OAuth 2.0 or API key                    |
| Best for          | Cursor, VS Code, local Claude/Gemini setups | ChatGPT, Claude, any URL-based client   |
| Setup             | [Local install (npm)](/mcp/npm-package)     | [Getting started](/mcp/getting-started) |

Both paths end at the same tenant-scoped gateway, so the tools, resources, and prompts you get are identical. The only difference is where the server process runs and how you authenticate.

## Cloud endpoint

```
https://api.getsmartalex.com/functions/v1/mcp-server
```

Point any HTTP-capable MCP client at that URL and authenticate with [OAuth or an API key](/mcp/authentication).

## Stateless by design

The cloud server runs **stateless**: each request spins up a fresh server instance, handles the call, and tears down. There's no long-lived session to keep alive.

For you this means one thing: if a client shows a reconnection notice, just reconnect, every request is independent, so nothing is lost.

## Workspace isolation

Every credential resolves to exactly one workspace. An API key belongs to the workspace it was created in; an OAuth token resolves to the user's active workspace. The gateway scopes every read and write to that workspace, so one credential can never reach another tenant's data.

<CardGroup cols={2}>
  <Card title="Authentication" href="/mcp/authentication">
    API keys, OAuth, scopes, and rate limits.
  </Card>

  <Card title="Getting started" href="/mcp/getting-started">
    Connect a client in two minutes.
  </Card>
</CardGroup>