Using the MCP Server

The Model Context Protocol (MCP) is an open standard for connecting AI agents to external tools and data sources. lightpaper.org provides an MCP server that gives agents access to the full publishing lifecycle — from account creation to document management — through a structured tool interface.

This means your AI agent doesn't need to know the REST API. It discovers available actions through MCP's tool discovery mechanism and uses them naturally as part of its reasoning process.

What Is MCP?

MCP is a protocol that standardizes how AI models interact with external services. Instead of the model generating raw HTTP requests, an MCP server exposes tools (actions the model can take) and prompts (templates the model can use). The model's runtime handles the connection and tool execution.

Think of it as a plugin system for AI agents. The agent connects to the MCP server, discovers what tools are available, and uses them when needed — all within its normal conversational flow.

Connecting to the Server

The lightpaper.org MCP server runs as a Python process. To connect it to an MCP-compatible client (like Claude Desktop or any MCP client library), add it to your MCP configuration:

{
  "mcpServers": {
    "lightpaper": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "env": {
        "LIGHTPAPER_API_KEY": "lp_free_yourkey"
      }
    }
  }
}

The server starts up, connects to the lightpaper.org API, and exposes its tools to the agent.

Available Tools

The MCP server provides 16 tools covering the full platform:

Publishing Tools

publish_document: Publish a new document with title, content, format, and metadata
update_document: Update an existing document's content or settings
get_document: Retrieve a document by ID
list_documents: List all documents for the authenticated account
delete_document: Remove a document permanently

Search and Discovery

search_documents: Full-text search across all public documents
browse_recent: Browse recently published documents
get_author_profile: View an author's public profile and publications

Account Management

get_account: Retrieve the authenticated account's details
update_account: Update display name, bio, or LinkedIn URL

Identity Verification

verify_domain: Start domain DNS verification
check_domain_verification: Check if DNS records have propagated
verify_linkedin: Begin LinkedIn OAuth verification
verify_orcid: Submit an ORCID iD for verification

Credentials

submit_credentials: Submit professional credentials (degrees, certifications, employment)
get_gravity_status: Check current gravity level, badges, and next-level instructions

Prompts

The server also provides two prompts that guide agent behavior:

`onboarding`

A structured workflow for new users. The agent walks the user through account creation, first publish, and identity verification. It adapts based on what the user has already completed.

`publish-workflow`

A focused prompt for the publishing process. The agent helps the user write or refine their content, choose the right format, and publish with optimal quality scoring.

Example Workflow

Here's how a typical interaction looks when an agent uses the MCP server:

User: "I want to publish my research notes about transformer architectures."

Agent (using MCP tools):

Calls get_account to check the user's current status
Calls get_gravity_status to see verification level
Helps the user structure their content as a paper
Calls publish_document with format "paper" and appropriate metadata
Reports back the URL, quality score, and suggestions for improvement
Suggests identity verification to boost gravity if not already done

The agent handles all the API details. The user just describes what they want to publish.

Agent-Driven Credential Verification

One of the more powerful MCP workflows is agent-driven credential verification. An AI agent can:

Ask the user about their professional background
Research the claims (checking LinkedIn profiles, university records, professional directories)
Submit credentials with an appropriate evidence tier
The author's gravity level updates automatically

This turns a potentially tedious manual process into a conversational one. The agent does the research, assesses the evidence, and submits everything through the API.

Building Your Own MCP Client

If you're building an application that integrates with lightpaper.org, you can use the MCP server directly. The MCP specification defines the protocol, and client libraries are available for Python and TypeScript.

The lightpaper.org MCP server uses the stdio transport — it communicates over standard input/output. This makes it easy to integrate into any application that can spawn a subprocess.

When to Use MCP vs. REST

Use the MCP server when:

Your agent supports MCP natively
You want the agent to discover tools dynamically
You prefer a conversational publishing workflow

Use the REST API directly when:

You're building a non-agent application
You want fine-grained control over every request
You're integrating with a CI/CD pipeline or automated system

Both approaches access the same underlying platform. The MCP server is a convenience layer that makes the API more natural for AI agents to use.