# McpServer

> Hosted MCP servers: your tools at one URL for any MCP client.

```python
server = noclick.McpServer.from_name("crm-tools", tools=["hubspot", "search"], create_if_missing=True)
print(server.url)   # paste into Claude, ChatGPT, Cursor or any MCP client
```

The tools are the ones a `Toolkit` or an agent takes (connections, single
operations, `search` and `fetch`), served over Streamable HTTP. Calls act in
the server's user's connections, under your policy, and bill like toolkit calls.
A name that is no connection there serves an integration's operations that need
no account, on NoClick's key: `tools=["exa.search"]` needs no connection.

## McpServer

```typescript
class McpServer
```

Your tools at one URL, for Claude, ChatGPT, Cursor or any MCP client. Anyone with `url` can call
the tools, so keep it like a key and `rotate()` it if it leaks. `toolCount` is how many tools it
serves right now (a connection that isn't connected serves none); `lastClientAt` is when any
client last talked to it.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string` |  |
| `url` | `string` | The URL MCP clients connect to; the path is its secret. |
| `tools` | `(string | JsonObject)[]` | What it serves, as you listed it: refs, and `{ tool, bind }` for an operation with arguments bound. |
| `toolCount` | `number` |  |
| `userId` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `lastClientAt` | `Date | null` | When a client last called it (null until one does). |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```

### McpServer.create

```typescript
static create(
  name: string,
  options: CallOptions & AllowExisting & { tools: McpServerTools },
): Promise<McpServer>
```

Create a server called `name` (unique per account and user; a duplicate throws `Conflict`
with `existingId`, or with `allowExisting: true` returns the server already there, as it is: its tools
don't change), serving at most 64 tools. A name is a connection in the server's user (the
account for an account server), else an integration's operations that need no account (on
NoClick's key), so `"exa.search"` needs no connection. Operations with arguments bound
(`hubspot.only(...).bind(...)`) keep them out of every client's reach; there `{{user...}}` is the
server's user.

Parameters:

- `name` (`string`, required)
- `options.tools` (`McpServerTools`, required)
- `options.allowExisting` (`boolean`): A taken name returns the object already there, as it is: nothing about it changes.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The new server, with the `url` to give your MCP client.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What a server serves: the refs an agent or a `Toolkit` takes, or a `Toolkit`. */
type McpServerTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };
```

### McpServer.fromName

```typescript
static fromName(
  name: string,
  options?: CallOptions & { tools?: McpServerTools; createIfMissing?: boolean },
): McpServer
```

A lazy reference to the server called `name` for the current (or given) user. Given `tools`, it gets
the server and sets them, on every run. `createIfMissing` creates it when there's none; without it, a
missing server throws `NotFound`. Its URL stays the same either way. Each run is a write: set the tools at startup or in a
setup script, and take the bare `fromName` in request handlers.

Parameters:

- `name` (`string`, required)
- `options.tools` (`McpServerTools`)
- `options.createIfMissing` (`boolean`)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A server that loads (or is created, or has your tools set) the first time you read a
field. Nothing is sent yet.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** What a server serves: the refs an agent or a `Toolkit` takes, or a `Toolkit`. */
type McpServerTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };
```

### McpServer.fromId

```typescript
static fromId(serverId: string, options?: CallOptions): McpServer
```

A lazy reference to a server by id.

Parameters:

- `serverId` (`string`, required)
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.

Returns: A server that loads the first time you read a field. Nothing is sent yet.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### McpServer.get

```typescript
static get(serverId: string, options?: CallOptions): Promise<McpServer>
```

Load a server by id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `serverId` (`string`, required)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The server, loaded.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### McpServer.list

```typescript
static list(options?: ReadOptions & { limit?: number }): Promise<McpServer[]>
```

The current user's servers (the account's own outside `asUser`, or those `userFilter` covers).

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Every matching server, newest first, fetched page by page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### McpServer.listPage

```typescript
static listPage(options?: ReadOptions & PageOptions): Promise<Page<McpServer>>
```

One page of servers; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A page whose `data` holds the servers and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### McpServer.update

```typescript
update(changes: { tools?: McpServerTools; name?: string }): Promise<this>
```

Change what it serves, or its name; the URL stays. A connected client sees new tools when it next lists them.

Parameters:

- `changes` (`{ tools?: McpServerTools; name?: string }`, required)

Returns: This server, updated.

Types:

```typescript
/** What a server serves: the refs an agent or a `Toolkit` takes, or a `Toolkit`. */
type McpServerTools = ToolRef[] | { refs: ToolRef[] };

/**
 * A tool ref: a name, `"name.operation"`, a capability, a `Connection`, `connection.only(...)`, a
 * `Database` or `db.only(...)`. A name is a connection in the scope the tools run in, else an
 * integration's operations that need no account (on NoClick's key), so `"exa.search"` needs no connection.
 * An entry read back from `agent.tools` (`{ tool, bind }`, `{ human, tools }`) is taken as it is.
 */
type ToolRef = string | Connection | ConnectionOperations | Database | DatabaseOperations | ToolSource | JsonObject;

type JsonObject = { [key: string]: unknown };
```

### McpServer.rotate

```typescript
rotate(): Promise<this>
```

Give it a new URL; the old one stops answering at once, so reconnect your clients with the new one.

Returns: This server, with its new `url`.

### McpServer.clients

```typescript
clients(): Promise<McpClient[]>
```

The MCP clients that have connected, most recently seen first: whether your agent has actually
started using the server, apart from whether the server is ready.

Returns: Each client's `name` and `version` as it reported them, when it was first and last seen,
and how many tools it listed. An empty list until a client connects.

### McpServer.delete

```typescript
delete(): Promise<void>
```

Delete the server; its URL stops answering. The connections it served stay.

## McpClient

```typescript
interface McpClient
```

An MCP client that has connected to a server, as it named itself (`Claude`, `cursor`). `toolCount`
is how many tools it saw when it last listed them: fewer than the server serves means it listed
them before you added some, and most clients list again only when a session starts.

| Attribute | Type | Description |
| --- | --- | --- |
| `name` | `string` |  |
| `version` | `string | null` |  |
| `firstSeenAt` | `Date | null` |  |
| `lastSeenAt` | `Date | null` |  |
| `toolCount` | `number | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```
