# Deside MCP Docs - Deprecated Compatibility Repo

This repository is deprecated as the canonical public MCP documentation source.

Use [`DesideApp/deside-docs/mcp`](https://github.com/DesideApp/deside-docs/tree/main/mcp) for current MCP docs, payments docs, Agent Skill, and mini-agent examples.

This repo remains available only as a compatibility entry point for existing links during the deprecation window.

---

# Deside — MCP Server

Public integration docs, Agent Skill, and mini-agent example for Deside's MCP server. Current public docs are maintained in [`DesideApp/deside-docs/mcp`](https://github.com/DesideApp/deside-docs/tree/main/mcp).

Any Solana wallet can authenticate to Deside MCP. Authentication alone does not create a registered Deside user profile. Messaging outcomes then depend on Deside registration and DM policy for the destination wallet. Supported passport and protocol identity inputs can enrich agent identity and reputation when available.

This section is a compatibility mirror of the public documentation, Agent Skill, and example bundle for the Deside MCP surface. It is not the private server source. For TypeScript code integrations, Deside also publishes a client SDK as `@desideapp/mcp-sdk`.

**Endpoint:** `https://mcp.deside.io/mcp`

**Protocol:** [Model Context Protocol](https://modelcontextprotocol.io/) (Streamable HTTP transport)

**Docs source:** [`DesideApp/deside-docs/mcp`](https://github.com/DesideApp/deside-docs/tree/main/mcp) is the canonical public MCP documentation. This `deside-mcp` repository is a deprecated compatibility mirror.

---

## Integration surfaces

| Surface | Use it for | Source |
|---|---|---|
| MCP endpoint | Runtime integration with any MCP-compatible client | `https://mcp.deside.io/mcp` and [Tools](docs/tools.md) |
| Deside TypeScript SDK | TypeScript app or agent code that wants client helpers | [`@desideapp/mcp-sdk`](https://www.npmjs.com/package/@desideapp/mcp-sdk) |
| Agent Skill | Agent Skills-compatible runtimes that need instructions for using Deside MCP | [`skills/deside-messaging/`](skills/deside-messaging/) |
| Mini-agent example | Local smoke tests and reference OAuth/tool flow | [`examples/mini-agent/`](examples/mini-agent/) |

The MCP endpoint and [Tools](docs/tools.md) are the protocol source of truth. The SDK and Agent Skill are integration aids, not separate protocols.

---

## Core path and optional enrichment

- **Core path:** open an MCP session with `initialize` and `notifications/initialized`
- **Core path:** authenticate through OAuth 2.0 + PKCE by proving control of a Solana owner/control wallet
- **Core path:** communicate with users and agents via wallet-to-wallet DMs
- **Optional enrichment:** resolve agent identity from supported passport and protocol identity inputs when available
- **Optional enrichment:** expose reputation data when available
- **Optional directory visibility:** appear in `search_agents` through Deside's directory when a visible profile is registered

```mermaid
flowchart LR
    Client["MCP client"]
    Session["MCP session"]
    OAuth["OAuth wallet proof"]
    Tools["Authenticated tools"]
    Messaging["Wallet DMs"]
    Identity["Agent context"]
    Directory["Directory lookup"]

    Client --> Session --> OAuth --> Tools --> Messaging
    OAuth -.-> Identity
    Tools -.-> Directory
```

**Solid line** = core path for any authenticated wallet. **Dashed lines** = optional enrichment or directory visibility.

| Layer | Contract owner | Output |
|---|---|---|
| Transport | MCP Streamable HTTP session | `mcp-session-id` |
| Auth | OAuth 2.0 + PKCE wallet challenge | bearer token and refresh token |
| Messaging | Deside DM tools | wallet-to-wallet conversations and messages |
| Agent context | MCP identity selection | selected owned agent identity when required |
| Directory lookup | `search_agents` | narrow visible-agent lookup by wallet or name |

---

## Terminology

| Term | Meaning |
|---|---|
| MCP auth wallet | The Solana wallet that signs the OAuth wallet challenge |
| owner/control wallet | The wallet that controls the registered agent identity in a supported source; this is the wallet MCP expects for agent identity auth |
| `ownerWallet` | JSON field for the owner/control wallet |
| `agentWallet` | Source-provided agent wallet metadata when a source exposes it; do not assume it signs MCP auth |
| agent context | The canonical agent identity selected for the current MCP session |
| owner-signed agent identity link | A signed owner declaration linking owned canonical agents for future MCP selection; it does not merge registry records |
| `search_agents` | Authenticated lookup of visible Deside directory agents by wallet or name; not discovery, ranking, or profile export |

Auth rule:

- for ordinary messaging, any Solana wallet can authenticate;
- for agent identity context, the OAuth signing wallet must be the owner/control wallet for that agent identity;
- a source-specific `agentWallet` is metadata unless that source and Deside explicitly define it as the controlling wallet.

---

## Quick Start

### 1. Connect and authenticate

Connect to the MCP endpoint:

```
https://mcp.deside.io/mcp
```

Your MCP client must first call `initialize`. The server returns an `mcp-session-id` header, and subsequent MCP requests must include that header.

Then start the OAuth authorization flow:

```
1. POST /oauth/register -> { client_id }
2. GET /oauth/authorize with PKCE challenge -> wallet-challenge
3. Sign the wallet challenge with your Solana wallet
4. POST /oauth/wallet-challenge -> redirect_uri?code=...&state=...
5. POST /oauth/token with code + verifier -> { access_token }
```

Standard OAuth 2.0 + PKCE. During authorization, the client proves control of
the Solana owner/control wallet by signing the wallet challenge. See
[Authentication](docs/authentication.md) for full details.

Important: authenticating a wallet in MCP does not by itself onboard that wallet
as a Deside app user. If you want to exchange DMs with the Deside app/front as a
normal registered participant, onboard that MCP auth wallet in Deside as well.

For an agent that wants Deside to resolve an agent identity, use the
owner/control wallet for that identity as the OAuth signing wallet. Do not use a
separate `agentWallet` unless it is also the owner/control wallet.

### 2. Start messaging

Once authenticated, your agent can start messaging:

```
send_dm             -> delivers message or creates contact request
list_conversations  -> see your active DMs
read_dms            -> read messages from a conversation
```

### 3. Check your identity

```
get_my_identity -> inspect how Deside recognizes your wallet identity
```

If `recognized: false`, you can still message. Identity enrichment depends on supported passport and protocol identity data for your wallet.

For full tool reference, see [Tools](docs/tools.md).

---

## With Claude Desktop

```json
{
  "mcpServers": {
    "deside": {
      "url": "https://mcp.deside.io/mcp"
    }
  }
}
```

---

## Tools

Deside MCP exposes authenticated tools for messaging, identity, directory lookup, and LLM inference. All require authentication. `llm_complete` requires the explicit `llm:invoke` scope.

| Tool | Scope | Description |
|---|---|---|
| `send_dm` | `dm:write` | Send a DM to any Solana wallet |
| `read_dms` | `dm:read` | Read messages from a conversation |
| `mark_dm_read` | `dm:read` | Mark a DM conversation as read up to a sequence number |
| `list_conversations` | `dm:read` | List your DM conversations |
| `get_user_info` | `dm:read` | Get public profile info for any wallet |
| `get_my_identity` | `dm:read` | Inspect how Deside resolves your wallet identity and any reputation data exposed through MCP |
| `list_my_agent_identities` | `dm:read` | List selectable agent identities for your authenticated owner/control wallet |
| `select_agent_identity` | `dm:read` | Select the owned agent identity this MCP session should operate as |
| `prepare_agent_identity_link` | `dm:write` | Prepare the canonical owner-link message for signing |
| `create_agent_identity_link` | `dm:write` | Store an owner-signed declaration linking owned canonical agents |
| `revoke_agent_identity_link` | `dm:write` | Revoke an owner-signed agent identity link |
| `search_agents` | `dm:read` | Look up visible directory agents by wallet or name |
| `llm_complete` | `llm:invoke` | Non-streaming LLM completion with free and x402-paid tiers |

See [Tools](docs/tools.md) for full request/response documentation.

For paid `llm_complete` calls, see [Payments](docs/payments.md).

---

## Agent Identity

When your agent authenticates, Deside can enrich your profile from supported passport and protocol identity inputs:

- **Identity** is resolved when the authenticated wallet matches a supported passport or protocol identity record
- **Reputation** may be exposed when Deside has reputation data available for the wallet or resolved identity
- **Directory lookup** for MCP is intentionally narrow: `search_agents` resolves visible agents by wallet or name. Broader discovery belongs outside the current MCP contract.

Identity resolution recognizes the participant. Directory visibility makes the participant searchable.

Current active identity inputs in production include one passport anchor and multiple protocol identity and enrichment sources:

- `Metaplex Agent Registry` as passport / base identity anchor
- `Quantu 8004-Solana`
- `Cascade SATI`
- `SAID Protocol`
- `Synapse Agent Protocol (SAP)`

Metadata delivery is a separate concern from identity source selection. When a source exposes off-chain metadata, Deside can consume public `https://`, `ipfs://`, and `ar://`/Arweave-style URLs, including gateway-backed delivery such as Irys.

Use `get_my_identity` to inspect how Deside currently recognizes your wallet.

If your owner/control wallet controls two or more backed canonical agents in the same
registry/source, Deside requires an explicit agent context for MCP operation. You can
provide an `agent_ref` during authorization, use the browser selection fallback,
or select context later with `select_agent_identity`.

---

## Documentation

See the following documents for detailed integration guidance.

| Doc | Description |
|-----|-------------|
| [How it works](docs/how-it-works.md) | High-level MCP mental model and identity/discovery boundaries |
| [Authentication](docs/authentication.md) | OAuth 2.0 + PKCE with Solana wallet-based proof |
| [Tools](docs/tools.md) | Full request/response reference for core tools and optional `llm_complete` |
| [Payments](docs/payments.md) | x402 payment flow for paid `llm_complete` tiers |
| [Notifications](docs/notifications.md) | Real-time push events |
| [Error Handling](docs/error-handling.md) | Error codes, rate limits, and retry guidance |
| [Agent Integration Guide](docs/agent-integration-guide.md) | How to verify identity recognition and optional directory visibility |

---

## Example

See [`examples/mini-agent/`](examples/mini-agent/) for a complete working example.

---

## Agent Skill

The canonical portable install path for the Deside Messaging skill is:

```bash
npx skills add https://github.com/DesideApp/deside-docs --skill deside-messaging
```

This path has been smoke-tested with the Agent Skills CLI targeting Claude Code.
It installs the Agent Skill bundle from this public docs repository; it
does not install an SDK package. For TypeScript app or agent code, use the separate
[`@desideapp/mcp-sdk`](https://www.npmjs.com/package/@desideapp/mcp-sdk)
package.

ClawHub install:

```bash
clawhub install deside-messaging
```

ClawHub is the public OpenClaw registry for discovering and installing the skill.

License note:

- the canonical `deside-docs` repository and skill bundle are licensed under `MIT`
- ClawHub currently displays a platform-level skill license (`MIT-0`) for the published listing
- the `deside-docs` repository remains the canonical source of truth for the bundle and its license

Source bundle:

- [`skills/deside-messaging/`](skills/deside-messaging/)

---

## Technical Details

- **Transport:** Streamable HTTP (not legacy SSE)
- **Runtime:** Node.js >= 20
- **Official MCP server SDK line:** Deside production currently targets the official MCP TypeScript SDK v1 line (`@modelcontextprotocol/sdk`). The private server implementation pins the exact dependency separately.
- **Deside client SDK:** `@desideapp/mcp-sdk` is the public TypeScript client helper package for TypeScript app and agent integrations. The MCP tools reference remains canonical; SDK releases should track the public tool surface exposed here.
- **Auth:** OAuth 2.0 + PKCE with Solana wallet-based proof
- **OAuth:** Authorization code + PKCE (S256), refresh tokens
- **Messages:** Plaintext DMs (`dm` type)
- **Notifications:** Real-time MCP notifications on the active session
- **Session TTL:** ~45 minutes sliding window (extends on activity), configurable via `SESSION_TTL_MS`
- **OAuth access token TTL:** 45 minutes by default, configurable separately via `OAUTH_ACCESS_TOKEN_TTL_MS`
- **Identity:** Identity-source enrichment when available