USCardForum MCP Server

How to use

Connect with a compatible MCP client using the streamable HTTP transport to access the server’s endpoints. You can browse hot topics, fetch topic details and posts, search the forum, inspect user profiles and activity, and perform authenticated actions like bookmarking posts or subscribing to topic updates. Use the streamable HTTP endpoint to integrate into web apps, tools, or automation pipelines.

To secure deployments, you can require a bearer token for the streamable HTTP transport. Clients authenticate by sending the Authorization header with a Bearer token. Local development can run without auth in stdio or server-sent events modes. When you deploy publicly, enable token-based auth to restrict access to your MCP endpoint.

For client configuration, point your MCP client at the deployed endpoint and supply any required token via headers. The server exposes the MCP API at the /mcp path of the chosen transport URL.

Examples of typical client capabilities you can build around include listing hot topics, retrieving a topic’s metadata and posts, performing full-text searches, examining user profiles and badges, and performing authenticated actions like bookmarking or subscribing to topics.

How to install

Prerequisites: you need Python installed for the pip-based path and the universal MCP runtime tool for the UV-based path. The server is designed to run with UV or pip installable package, and it supports multiple transport modes.

Option A: Install and run using UV (recommended for development and quick start)

# Install UV if you don’t have it yet
# Then clone the project repository
# Note: replace with your actual repository URL if you’re pulling a dedicated MCP server package

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Install with UV
uv sync

# Run the server with streamable HTTP transport
MCP_TRANSPORT=streamable-http MCP_PORT=8000 uv run uscardforum

# The MCP endpoint will be available at:
# http://localhost:8000/mcp
```} ,{

Option B: Install via pip (Python environment)

# Clone the repository
git clone https://github.com/uscardforum/mcp-server.git
cd uscardforum

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install the package in editable mode
pip install -e .

# Run the server (stdio transport is default and suitable for local development)
uscardforum
```}]} ,{

Notes about the two common run methods align with the following explicit examples you can adapt to your environment. If you deploy to a web-facing environment and want to constrain access, use the streamable HTTP transport with a bearer token.

Configuration and security

Transport modes and authentication are configurable to suit development and production deployments. The server supports three transport modes: stdio (default), server-sent events (sse), and streamable HTTP (recommended for web deployments). For deployments using streamable HTTP, you can enforce a bearer token via the NITAN_TOKEN environment variable.

Environment variables you may configure include MCP_TRANSPORT, MCP_HOST, MCP_PORT, NITAN_TOKEN, USCARDFORUM_URL, USCARDFORUM_TIMEOUT, NITAN_USERNAME, and NITAN_PASSWORD. The standard approach is to set MCP_TRANSPORT to streamable-http for web deployments, and to provide a token in NITAN_TOKEN when you require authentication.

Cursor IDE integration and Claude Desktop integration are supported through MCP server entries that point to the running UV-based process, enabling convenient work-flows for testing and development.

Testing and examples

You can run integration tests against the live forum by providing test credentials. Use the standard test workflow to verify search, topic retrieval, and user data access works as expected.

A practical example of connecting a client is to reference the deployed endpoint and attach an Authorization header when using streamable HTTP. For local development, you can connect to http://localhost:8000/mcp without additional headers if you are using stdio transport.

Code examples below show how to start the server with streamable HTTP and how a client can be configured to connect.

{
  "mcpServers": {
    "uscardforum": {
      "url": "https://<your-host>/mcp",
      "headers": {
        "Authorization": "Bearer <your-nitan-token>"
      }
    }
  }
}
```}]} ,{

Tools and endpoints overview

The MCP server exposes a wide range of tools grouped into Discovery, Reading, Users, and Auth categories. These tools allow you to list topics, fetch topic data, explore user profiles and actions, and perform authenticated actions like bookmarking posts and subscribing to topics.

Notes

If you are deploying to a hosting platform, consult the platform’s guidance for securely handling environment variables and configuring TLS termination. For local development, you can start quickly with the stdio transport and expand to streamable HTTP as your needs grow.

get_hot_topics

Return a list of currently trending topics by engagement to discover what people are discussing now.

get_new_topics

Return a list of the newest topics by creation time so you can catch fresh discussions.

get_top_topics

Return a list of top topics over a period (daily/weekly/monthly/yearly) to see popular discussions.

search_forum

Perform a full-text search with operators to locate topics and posts across the forum.

get_categories

Retrieve a mapping of category IDs to human-friendly category names.

get_topic_info

Fetch metadata about a topic, including post counts and other statistics.

get_topic_posts

Fetch a subset of posts from a topic, with pagination support.

get_all_topic_posts

Fetch all posts in a topic by iterating through pages.

get_user_summary

Return a compact profile overview for a user, including stats and badges.

get_user_topics

List topics created by a specific user.

get_user_replies

Retrieve a user’s reply history within topics.

get_user_actions

Fetch the full activity feed for a user.

get_user_badges

List badges earned by a user.

get_user_following

Show users that a given user follows.

get_user_followers

Show users that follow a given user.

get_user_reactions

Retrieve reactions given and received by a user.

list_users_with_badge

Find users who have earned a specific badge.

login

Authenticate with the forum using provided credentials to obtain a session.

get_current_session

Check whether a user is authenticated and retrieve current session details.

get_notifications

Fetch the authenticated user’s notifications.

bookmark_post

Bookmark a specific post for later reference.

subscribe_topic

Set or modify the notification level for a topic.