Documentation navigation

Djass MCP Server

Connect to hosted Djass MCP to generate and download a Django repository under your Djass account. Enable Use MCP only when your generated application also needs its own agent connection. These are separate servers with separate credentials and tools; neither a successful connection nor a generated scaffold implements your application's customer-access policy.

Hosted Djass also exposes an authenticated FastMCP Streamable HTTP endpoint at /mcp. Use a Djass API key in the Authorization: Bearer <key> header.

Hosted endpoint

  • Endpoint: https://djass.dev/mcp
  • Setup prompt: https://djass.dev/mcp/prompt
  • ZIP download route: https://djass.dev/mcp/projects/{project_id}/download

Remote agents should call get_generator_options, then create_project, poll get_project_status, and finally call get_project_download. The download response includes a URL plus the checksum; fetch that URL with the same API-key header.

For a copy-ready setup prompt, see Generate a Project With an AI Agent.

For one-command installation with the skill and MCP connection bundled, use the official plugin from LVTD-LLC/djass-skills. It covers Claude Code, OpenAI Codex, Cursor, OpenClaw, OpenCode, and any Agent Skills client.

Codex setup

Djass hosted MCP is authenticated. Adding only the URL lets Codex reach the server, but it does not send a Djass API key, so the MCP initialization request is rejected with 401 invalid_token.

  1. Open Account settings and copy your Agent API key. If you use a scoped project API key instead, grant projects:create and projects:read. Expected outcome: you have a key that can create projects and read generated project artifacts.

  2. Save the key in your shell environment:

bash export DJASS_API_KEY="..."

Expected outcome: DJASS_API_KEY is available to Codex as a secret environment variable.

  1. Add the hosted Djass MCP server to Codex:

bash codex mcp add djass --url https://djass.dev/mcp --bearer-token-env-var DJASS_API_KEY

Expected outcome: Codex stores a djass MCP server that sends Authorization: Bearer <DJASS_API_KEY> to the hosted endpoint.

  1. Verify the server configuration:

bash codex mcp list

Expected outcome: djass appears in the configured MCP server list.

  1. Restart Codex after updating the environment. Expected outcome: the configured MCP server can read DJASS_API_KEY, and MCP initialization no longer fails with 401 invalid_token.

Hosted tools

  • get_generator_options returns supported Cookiecutter fields, defaults, grouped feature flags with labels and descriptions, and the active template path.
  • create_project queues a project generation job for the authenticated Djass user.
  • list_projects lists projects for the authenticated Djass user.
  • get_project_status fetches one project and includes download metadata when the artifact is ready.
  • get_project_download returns the authenticated ZIP download URL and checksum for a ready project.

Choose the right server and credentials

Hosted Djass generates the repository. Its MCP tools use your Djass account: create_project requires projects:create; listing projects, polling status, and retrieving the ZIP require projects:read. A scoped read-only key cannot queue generation. Project lookups are limited to the authenticated account. The Projects API reference documents the related REST endpoints and scope errors. Keep credentials in headers, not URLs or logs.

Your generated app serves your customers. In the bundled starter checked on October 25, 2026, enabling use_mcp includes apps/mcp_server, its OAuth flow, and a get_user_info tool. That tool returns the authenticated user's account/profile information through the same serializer as GET /api/user. It does not create Djass generation jobs or expose your future product models. The response excludes API keys but includes personal account fields such as email: treat it as authenticated data, not public content.

The generated MCP connection supports OAuth and legacy API-key headers. Use credentials issued by that generated app; do not reuse your hosted Djass key or assume the hosted projects:read scope applies there. The starter's OAuth scope is mcp:user, not a ready-made set of per-feature read/write roles. Inspect the generated app's own MCP access documentation for its URLs and setup prompt. With use_mcp=n, the MCP app is removed; you can still use hosted Djass MCP to generate the repository.

Verify the handoff before adding tools

After starting the generated app locally, check these boundaries with disposable accounts, not customer credentials:

  1. Connect to the generated app's MCP URL with its supported authentication flow. Call get_user_info and confirm it identifies that app's signed-in account. The same email on both services does not make their credentials interchangeable.
  2. Repeat with a second account. Confirm each response belongs to its caller and contains no API key. An authenticated response is not evidence that future tools will enforce ownership.
  3. Check that missing credentials fail. For OAuth, also exercise expired and revoked access tokens; a cached client connection must not be your proof that access still works. The starter checks token expiry and revocation, but your deployed configuration still needs verification.

Give a new product tool an explicit access rule

Before asking a coding agent to add a tool, use this build brief:

Implement one customer action in the generated repository. Resolve the authenticated account on the server; do not accept a caller-supplied owner as proof of identity. Share the action's service and ownership policy with any REST/view entrypoint. Prove account A can operate on A's record but cannot list, read, change, delete, export, or queue work for B's record by changing an argument. Rejected writes must leave data unchanged. Test missing credentials and any additional action privileges. Report the exercised paths and remaining deployment checks; a tool being hidden from the client is not authorization.

This is a feature acceptance contract, not functionality already generated. Use the owner-scoped feature workflow to design record access. For HTTP token handling and resource boundaries, consult the MCP authorization specification (2025-11-25). That specification is a reference, not a claim that every starter integration has passed a protocol or security assessment.

Local development

Use local stdio only when you are developing Djass itself or intentionally need the MCP server and agent to share a filesystem.

From the repository root:

uv run python -m apps.mcp.server

Installed environments can also use:

djass-mcp

The default transport is stdio, which is the normal mode for local MCP clients. Set DJASS_MCP_TRANSPORT=streamable-http only when you intentionally want the SDK HTTP transport for a separate local MCP process. Hosted Djass uses FastMCP's Streamable HTTP ASGI app mounted at /mcp, with Django-owned prompt and ZIP download endpoints beside it.

Local client configuration example

{
  "mcpServers": {
    "djass": {
      "command": "uv",
      "args": ["run", "python", "-m", "apps.mcp.server"],
      "env": {
        "DJANGO_SETTINGS_MODULE": "djass.settings",
        "DJASS_MCP_USER_EMAIL": "[email protected]"
      }
    }
  }
}

Local stdio tools

  • get_generator_options returns supported Cookiecutter fields, defaults, grouped feature flags with labels and descriptions, and the active template path.
  • create_project creates a Project row and queues background generation through Django Q2.
  • get_project fetches one project by id.
  • list_projects lists projects, optionally scoped by user email and status.
  • export_project_artifact writes a ready artifact zip to the MCP server filesystem and optionally extracts it. Use this only when the MCP server and agent share a filesystem, such as local stdio MCP.

Resources

  • djass://generator/options
  • djass://projects/{project_id}
  • djass://projects/{project_id}/artifact.zip

Local stdio automation identity

If user_email is omitted in tool calls, the MCP service uses DJASS_MCP_USER_EMAIL, falling back to [email protected]. Missing MCP users are created with an unusable password and granted project generation access so local agents can operate without a manual signup flow.

Queued generation and artifacts

Agents should call get_generator_options first, then ask the user which optional feature flags and generator options they need and will use. Do not infer services such as analytics, payments, storage, support chat, keyboard shortcuts, CI, or MCP scaffolding from a vague app idea. If the user asks for Djass defaults, treat that as explicit confirmation.

Use create_project to create a queued generation job, then poll get_project_status until the status is ready or failed.

When artifact_ready is true, retrieve the generated repository ZIP from the download URL returned by get_project_download. Hosted MCP servers cannot write into the agent's local workspace, so the MCP client should save and unzip the artifact on the client side.

For local stdio MCP servers that share a filesystem with the agent, agents can call export_project_artifact with extract=true to write and unpack the ZIP. Set overwrite=true only when replacing an existing generated zip or extract directory is intentional.

use_apprise, use_qdrant, and use_mcp are available as normal "y"|"n" generator flags on create_project. use_apprise controls the generated admin notification helper and docs; use_qdrant adds authenticated client configuration but does not provision Qdrant or define vector workflows; use_mcp controls whether the generated repository includes MCP scaffolding and does not control whether the hosted Djass MCP server itself is used.