The UnderSelf MCP server exposes six tools, record_dream, analyze_dream, get_dream, list_dreams, search_dreams and get_patterns, that let a connected AI assistant save, read and search your own dream journal and see the patterns across it.
Updated September 24, 2026
You never have to name a tool; your assistant picks one from what you say. This page is for the curious and for developers. Not connected yet? Connect an assistant first.
About the examples.Every example below is made up: a gentle dream about a house with extra rooms, and placeholder ids. Field names are exactly what the tools return. Long text is shortened.
| Tool | Title | Scope | Counts against your plan |
|---|---|---|---|
record_dream | Record a dream | dreams:write | Yes, as in the app: a new dream and one message, plus a reading unless analyze is false |
analyze_dream | Get a reading | dreams:write | Yes: a reading |
get_dream | Open a dream | dreams:read | No |
list_dreams | List dreams | dreams:read | No |
search_dreams | Search dreams | dreams:read | No |
get_patterns | See your patterns | dreams:read | No |
Saves a dream to your journal and, by default, gives you its reading. If you send the same text again within 10 minutes, you get the earlier dream back instead of a second one, so a retry never spends another dream.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
text | string | Yes | The dream in your own words, 20 to 20,000 characters. |
date | string | No | The night of the dream, YYYY-MM-DD. Defaults to today. |
language | string | No | ISO 639-1 code for the reading, such as en. Defaults to your account language. |
analyze | boolean | No | Also make a reading now. Default true. |
length | string | No | short (default) or long, on plans that include longer readings. |
{
"dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
"status": "analyzed",
"reading": {
"mood": "peaceful",
"phase": "threshold",
"essenceText": "A familiar home quietly making room for more of you.",
"interpretation": "The house is a common image for the self. Finding new rooms in a place you know well often arrives when...",
"archetypes": ["Explorer", "Child"]
},
"answer": "What a lovely dream to wake up with. The rooms you had never seen..."
}Other shapes you may see: { "dream_id", "status": "recorded" } when analyze is false; the same plus "duplicate": true and a note for a repeat within 10 minutes; "status": "recorded" with a note when the dream saved but the reading did not (for example, a slow reading or a reached reading limit); and "status": "needs_more_info" with a reason and an answer when the text is too thin to read, so the reading asks you for more detail instead of guessing.
Gives a new reading of a dream already in your journal. Useful after you add detail, or for a longer reading.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
dream_id | string (UUID) | Yes | From record_dream, list_dreams or search_dreams. |
language | string | No | ISO 639-1 code. Defaults to your account language. |
length | string | No | short (default) or long. |
{
"dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
"status": "analyzed",
"reading": {
"mood": "peaceful",
"phase": "integration",
"essenceText": "Room to grow inside what already feels like home.",
"interpretation": "Read more slowly, the unopened doors...",
"archetypes": ["Explorer", "Sage"]
},
"answer": "Coming back to this dream, what stands out is..."
}Like record_dream, it can return "status": "needs_more_info" with a reason and an answer. If a reading runs long, the tool says so; check with get_dream a minute later before asking again.
Opens one dream with its full text, its summary and its latest reading.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
dream_id | string (UUID) | Yes | The dream to open. |
{
"dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
"date": "2026-09-23",
"text": "I was in my grandmother's house and every door opened onto a room I had never seen...",
"summary": "Walking through a familiar house that keeps opening onto new rooms.",
"reading": {
"mood": "peaceful",
"phase": "threshold",
"essenceText": "A familiar home quietly making room for more of you.",
"interpretation": "The house is a common image for the self...",
"archetypes": ["Explorer", "Child"],
"answer": "What a lovely dream to wake up with...",
"created_at": "2026-09-23T07:12:40.000Z"
},
"reading_count": 1
}reading is null when the dream has no reading yet, and summary is null until one is written.
Lists your dreams, newest first, one page at a time.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
limit | integer | No | 1 to 50. Default 20. |
page | integer | No | Starts at 1. Default 1. |
date | string | No | Only dreams from this night, YYYY-MM-DD. |
{
"dreams": [
{
"dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
"date": "2026-09-23",
"summary": "Walking through a familiar house that keeps opening onto new rooms.",
"has_reading": true
}
],
"page": 1,
"total": 14,
"total_pages": 1
}Finds dreams whose text or summary mention some words. Only the first 100 characters of the query are used, so short queries work best.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
q | string | Yes | Words to look for. Longer input is cut to the first 100 characters. |
limit | integer | No | 1 to 50. Default 20. |
{
"query": "house",
"dreams": [
{
"dream_id": "3f2a9c1e-0000-4000-8000-000000000001",
"date": "2026-09-23",
"summary": "Walking through a familiar house that keeps opening onto new rooms.",
"has_reading": true
}
],
"total": 3
}Shows the themes running through your dreams: your latest insights chapter, how often you have recorded lately, and your Inner Map. Each part can be missing, and notes says which and why.
Things you might say
| Input | Type | Required | Notes |
|---|---|---|---|
language | string | No | ISO 639-1 code. The Inner Map comes in en, fr, de and ru; other codes use your account default for it. |
{
"chapter": {
"headline": "Rooms you have not opened yet",
"body": "Across your recent dreams, homes keep appearing, and each one is bigger on the inside...",
"reflectiveQuestion": "What part of your life feels ready for more space?",
"voices": [{ "name": "Explorer", "line": "There is always one more door." }],
"journeyLine": "From closed doors to open ones.",
"dominantPhase": "threshold",
"dreamCount": 9,
"generatedAt": "2026-09-22T06:30:00.000Z"
},
"activity": { "last_7_days": 3, "last_30_days": 9, "last_90_days": 14 },
"inner_map": {
"lead": "Explorer",
"topThree": ["Explorer", "Sage", "Child"],
"scores": { "Explorer": 9, "Sage": 7, "Child": 6 },
"descriptions": [
{ "archetype": "Explorer", "title": "The Explorer", "blurb": "Drawn to what lies past the edge of the map..." }
],
"aiNote": null
},
"notes": []
}scores holds points for all eight Inner Map archetypes; three are shown here. Typical notes: "No insights chapter yet; it appears after a few recorded dreams." and "No Inner Map yet; it appears after the Inner Map quiz in the UnderSelf app."
dreams:read covers get_dream, list_dreams, search_dreams and get_patterns. dreams:write covers record_dream and analyze_dream. The consent page lists the ones your assistant asked for; most ask for both.Every error sentence, the OAuth flow and token lifetimes are in the technical reference.