# MCP

The four MCP tools, remote plugin connection and signed local agent bridge.

Lys exposes four MCP tools over its admitted HTTP router. The remote plugin uses host OAuth; the local bridge signs requests as the enrolled agent. A listed tool or route grants no additional authority.

## Connect as the agent

For Claude Code or Codex with host OAuth, use the [Lys plugin](/lys/plugin/). For a signed local connection, use the bridge below.

An agent's own MCP connection to Lys, over stdio: each JSON-RPC message read on stdin is signed with the agent's key (`lys-agent-signature`) and posted to Lys's MCP route, and the answer written on stdout. Calls carry the agent's own grants and meet Lys's own refusals; the bridge grants nothing. The key is never printed

```text
lys mcp [OPTIONS] --url <URL> --agent <AGENT> --key-file <KEY_FILE>
```

- `--url <URL>`: The installed Lys MCP route on numeric loopback HTTP, such as http://127.0.0.1:8490/api/mcp.
- `--agent <AGENT>`: The agent the messages are signed as (`agent-…`).
- `--key-file <KEY_FILE>`: The agent's key: a PKCS#8 PEM file, or a seat file whose `privateKeyPem` holds it.


The key-file argument accepts a PKCS#8 PEM or a seat file carrying that key. Supply the Lys agent identifier enrolled for that key. The local bridge accepts numeric loopback HTTP and signs the message for the service's path beneath its API mount.

**A signed local MCP connection**

```json
{
  "mcpServers": {
    "lys": {
      "command": "lys",
      "args": [
        "mcp",
        "--url",
        "http://127.0.0.1:8490/api/mcp",
        "--agent",
        "<the Lys agent id enrolled for this key>",
        "--key-file",
        "/private/lys/agent.seat.json"
      ]
    }
  }
}
```


These example paths and the agent identifier are deployment inputs. Keep the key in its private file and do not paste it into the launcher.

## Discover authority first

**Discover the current connection’s authority**

```json
{"name":"what-can-I-do","arguments":{}}
```


## Reading

- `what-can-I-do` (): List the routes, resources and actions this connection may reach under its live grants. A tool listing grants no authority; mode-specific requirements and route admission still apply.
- `read` (path, body?, method?): Read through an existing HTTP route with the caller's credentials and admission. A tool listing grants no authority; mode-specific requirements and route admission still apply.


**Read through MCP**

```json
{"name":"read","arguments":{"method":"GET","path":"/health"}}
```


## Changes and drafts

- `change` (method, path, body?): Change through an existing HTTP route. Its validation, authority checks and refusals apply unchanged. A tool listing grants no authority; mode-specific requirements and route admission still apply.
- `drafts` (path, body?, method?): Ask an existing draft route with the caller's credentials. This transport grants no draft authority. A tool listing grants no authority; mode-specific requirements and route admission still apply.


The drafts tool can read or change a draft route; its classification here includes writing. Each route retains its normal validation and authority checks.

## Transport and failures

The installed HTTP contract declares POST for messages. Read the live transport response rather than assuming GET provides a stream. A refused signature is different from a tool result refusing a resource action. The bridge can exit successfully after relaying such a refusal, so inspect the JSON response as well as the process exit.