Zulip Terminology Reference
Understanding Zulip’s terminology is crucial for effective use of the MCP server. This guide explains key concepts and their equivalents in other platforms.
Core Concepts
Streams vs Channels
The most important concept to understand:
| Zulip Term |
Other Platforms |
Description |
| Stream |
Channel (Slack/Discord), Team (Teams) |
Main conversation spaces for topics |
| Topic |
Thread (Slack), Thread (Discord) |
Focused discussions within streams |
Key Points:
- Streams = Channels - These terms are completely interchangeable
- This MCP server uses “stream” to match Zulip’s official terminology
- If you’re familiar with Slack “channels” or Discord “channels”, Zulip “streams” work identically
Message Organization
Organization
├── Stream #1 (e.g., "Development")
│ ├── Topic: "Sprint Planning"
│ ├── Topic: "Code Reviews"
│ └── Topic: "Bug Reports"
├── Stream #2 (e.g., "General")
│ ├── Topic: "Announcements"
│ └── Topic: "Random Chat"
└── Direct Messages
├── 1:1 conversations
└── Group conversations
Stream Types and Properties
Stream Privacy Levels
| Type |
Description |
Who Can Join |
Message Visibility |
| Public |
Open to all organization members |
Anyone can subscribe |
Messages visible to all subscribers |
| Private |
Invitation-only |
Only invited members |
Messages only visible to subscribers |
| Web Public |
Publicly accessible |
Anyone on internet |
Messages visible to anyone with link |
| Announcement-only |
Read-only for most users |
Admins control posting |
Limited posting permissions |
Stream Settings
- invite_only: Boolean indicating if stream is private
- is_web_public: Stream is accessible without login
- is_archived: Stream is archived (read-only)
- is_announcement_only: Only designated users can post
Topics: Zulip’s Threading System
What Makes Topics Special
Unlike other platforms where threads are optional, Zulip requires topics for all stream messages:
Stream: #development
├── Topic: "Sprint 23 Planning" ← All messages about sprint planning
├── Topic: "API Rate Limiting Fix" ← All messages about this bug
└── Topic: "Code Review Process" ← All messages about reviews
Topic Benefits
- Perfect Organization: Every message has a clear context
- Easy Catching Up: Read only topics relevant to you
- Persistent Discussions: Topics maintain focus over time
- Search Efficiency: Find conversations by topic name
Topic Best Practices
- Descriptive Names: “API Bug Fix” not “Bug”
- Specific Scope: One topic per discussion thread
- Consistent Naming: Follow team conventions
- Update When Scope Changes: Rename topics if discussion evolves
User Roles and Permissions
Organizational Roles
| Role |
Permissions |
Description |
| Owner |
Full admin + ownership transfer |
Organization founder/owner |
| Administrator |
All admin functions |
Full management access |
| Moderator |
Stream and user moderation |
Content and behavior management |
| Member |
Standard user access |
Regular team member |
| Guest |
Limited access to specific streams |
External collaborators |
| Bot |
Automated access via API |
Integration and automation |
Stream-Level Permissions
- Stream administrators: Manage specific streams
- Subscribers: Members who receive stream notifications
- Posting permissions: Who can send messages to streams
Message Features
Mentions and Notifications
| Syntax |
Effect |
When to Use |
@**Full Name** |
Standard mention with notification |
Direct someone’s attention |
@_**Full Name**_ |
Silent mention (no notification) |
Reference without interrupting |
@**all** |
Mentions everyone in organization |
Important announcements only |
@**stream** |
Mentions all stream subscribers |
Stream-wide announcements |
@**topic** |
Mentions all topic participants |
Topic-specific updates |
Stream and Topic References
#**stream-name** - Link to a stream#**stream-name>topic-name** - Link to specific topic#**stream-name>topic-name@messageID** - Link to specific message
Message Types
| Type |
Description |
Use Cases |
| Stream Message |
Public message in a stream topic |
Team discussions, announcements |
| Direct Message |
Private 1:1 or group message |
Private conversations, sensitive topics |
| Scheduled Message |
Message sent at future time |
Reminders, time-zone coordination |
| Draft |
Saved unsent message |
Work-in-progress, offline composition |
Coming from Slack
| Slack Concept |
Zulip Equivalent |
Key Difference |
| Channel |
Stream |
Same concept, different name |
| Thread |
Topic |
Topics are required and more prominent |
| DM |
Direct Message |
Same functionality |
| Workspace |
Organization |
Same concept |
| App/Bot |
Bot |
Same integration capabilities |
Coming from Discord
| Discord Concept |
Zulip Equivalent |
Key Difference |
| Server |
Organization |
Same concept |
| Channel |
Stream |
Same concept, different name |
| Thread |
Topic |
Topics are more central to Zulip |
| DM |
Direct Message |
Same functionality |
| Role |
Role |
Similar permission system |
Coming from Microsoft Teams
| Teams Concept |
Zulip Equivalent |
Key Difference |
| Team |
Organization |
Same concept |
| Channel |
Stream |
Same concept, different name |
| Conversation |
Topic |
Topics are more structured |
| Chat |
Direct Message |
Same functionality |
MCP Server Terminology Usage
The MCP server uses “stream” terminology because:
- Official Zulip API uses “stream” in all endpoints
- Consistency with Zulip documentation and UI
- Clarity for developers working with Zulip API
- Future-proofing as Zulip evolves
| MCP Tool |
Function |
Zulip API Endpoint |
get-subscribed-streams |
List user’s stream subscriptions |
/api/v1/users/me/subscriptions |
get-stream-id |
Get stream ID by name |
/api/v1/get_stream_id |
get-stream-by-id |
Get stream details |
/api/v1/streams/{id} |
get-topics-in-stream |
List topics in stream |
/api/v1/users/me/{id}/topics |
Resource URI Schemes
zulip://streams - Browse available streamszulip://users - Browse organization memberszulip://formatting/guide - Message formatting referencezulip://patterns/common - Usage patterns and workflows
Common Workflow Terminology
Message Workflow Terms
- Send: Create and deliver a message
- Edit: Modify existing message content or topic
- React: Add emoji reaction to message
- Quote: Reference another message in your reply
- Star: Bookmark message for later reference
- Pin: Highlight important message in topic
Stream Management Terms
- Subscribe: Join a stream to receive messages
- Unsubscribe: Leave a stream
- Mute: Stop notifications from stream/topic
- Archive: Make stream read-only and hide from lists
- Pin: Keep stream at top of sidebar
Organization Terms
- Realm: Zulip’s internal term for organization
- Domain: Email domain for organization members
- Custom Profile Fields: Additional user information fields
- Emoji: Custom emoji specific to organization
Best Practices for MCP Usage
- Stream Discovery: Always use
get-subscribed-streams to see exact stream names
- User Search: Use
search-users before sending direct messages
- Topic Clarity: Include descriptive topics for all stream messages
- Error Handling: Tool error messages guide you to correct syntax
Common Mistakes to Avoid
| Mistake |
Correct Approach |
Tool to Use |
| Using display names for DMs |
Use actual email addresses |
search-users |
| Wrong stream name spelling |
Use exact names from API |
get-subscribed-streams |
| Forgetting topic for streams |
Always include topic parameter |
N/A (required) |
| Assuming stream exists |
Verify stream access first |
get-stream-id |
Terminology in Error Messages
The MCP server provides helpful error messages:
- “Stream not found” → Check exact spelling with
get-subscribed-streams
- “User not found” → Use email addresses from
search-users
- “Topic required” → Include topic parameter for stream messages
- “Permission denied” → Check bot permissions in Zulip settings
Quick Reference
Essential Zulip Concepts
- Streams = Channels (conversation spaces)
- Topics = Required thread names for stream messages
- Direct Messages = Private conversations
- Mentions =
@**Name** syntax for notifications
- Stream Links =
#**stream-name** for references
- Helper Tools:
get-started, search-users
- Stream Tools:
get-subscribed-streams, get-stream-id, get-stream-by-id, get-topics-in-stream
- Message Tools:
send-message, get-messages, get-message, edit-message
- User Tools:
get-users, get-user-by-email, get-user
Understanding these concepts will help you use the Zulip MCP Server effectively and communicate clearly with your team about Zulip features and functionality.