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

# Hooks or MCP: two ways to connect an agent

> Compare the two ways to connect an agent to Little Spaces, hooks installed on your computer and the remote MCP server, and choose the right one for each app.

An agent can reach Little Spaces in two ways: through **hooks** that setup installs on your computer, or through Little Spaces' **MCP server**. Both let an agent report and get your answers. The difference is that hooks know about a session without the agent doing anything, while the MCP server only knows what the agent chooses to tell it.

## The two words

* **Hooks** are small commands that an app runs by itself at moments in a session: when it starts, when you send a message, when a turn ends, when it closes. The prompt on the **Agents** page installs Little Spaces' hooks in each app on your computer, in that app's own user-level files.
* **MCP** (the Model Context Protocol) is a standard way for an AI app to use tools from a server. An app connected to Little Spaces' MCP server gets tools such as `report_activity` and `get_answers`, and uses them when it decides to.

## How they compare

| | Hooks (the Agents page prompt) | MCP server |
| - | - | - |
| **Session shows under Runs** (running, waiting, stalled, ended) | Yes, automatically, from the app's own events. | Only if the agent sends its own liveness signals (`signal_run`). Reports alone appear in Activity. |
| **Told how to report** | Yes, by the text each session gets when it starts. | Only by the server's instructions and tool descriptions, so it depends on the agent reading them. |
| **Reports and asks** | Yes (`spaces report`). | Yes (`report_activity`). |
| **Gets your answers** | Brought to the session by its hooks, at the end of a turn or with your next message, depending on the app. An idle Claude Code session can be woken. Pi and OpenCode v2 are built to be woken too, but this hasn't yet been seen working in a real session. | Only when the agent next calls `get_answers`. It can't be woken. |
| **Reminded of open asks when you send a message** | Yes, in apps whose hooks see your messages. | No, though its tool descriptions tell it to report when you answer in the session. |
| **Nudged when it seems to wait on you without asking** | Yes, in Claude Code and Codex. | No. |
| **Reads activity and asks questions about it** | Yes (`spaces activity`, `spaces ask`). | Yes (`get_activity`, `ask_work`). |
| **Works on to-dos you've approved** | No. The hooks' sign-in can only read and report. | Yes, if you allow **Work on tasks you've approved** when you approve it. |
| **Identity** | One per computer, such as "Hooks on laptop". Each report says which app sent it. | One per connection, so each app you connect is an agent of its own. |
| **Where it works** | Agents on a Mac or Linux computer you control. | Anywhere, including hosted assistants with nothing to install. |

## When to use which

* **Use hooks** for any coding agent on your own computers. It is the default: you get each session under Runs, and your answers delivered.
* **Use MCP** for a [hosted assistant](https://docs.littlespaces.dev/connecting-agents/hosted-assistants.md), or for an app that needs an identity of its own or permission to work on to-dos you've approved.

> [!WARNING]
>
> Connecting one app both ways gives it two identities. Its MCP reports then don't join the session its hooks created under Runs.

## Connect an app over MCP

The MCP server is at `https://api.littlespaces.dev/mcp`, the URL the **Agents** page shows under **Connect a hosted assistant**. Add it once per app on each computer. For example:

```bash Claude Code theme={null}
claude mcp add --transport http little-spaces https://api.littlespaces.dev/mcp
```

```bash Codex theme={null}
codex mcp add little-spaces --url https://api.littlespaces.dev/mcp
codex mcp login little-spaces
```

The app registers itself and opens an approval page in your browser. There you name the agent and decide whether it may **Work on tasks you've approved**, which is on by default; turn it off for an agent that should only report and ask you questions. Then choose **Allow**. The app stores and renews its own credentials.

Sign-in can't start inside a non-interactive session, so run the login once in a terminal.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.