{
  "schema_version": "1.2",
  "kind": "boardwalk.land_use.api_connection_manifest",
  "description": "Machine-readable connection metadata for Boardwalk land-use intelligence. Distinguishes the subscriber OAuth + remote MCP path (Claude Connectors) from the API-key path used by developers, Cursor skills, and Custom GPT Actions.",
  "product": {
    "name": "Boardwalk",
    "support_email": "support@boardwalkai.com"
  },
  "legal": {
    "privacy_policy_url": "https://boardwalkai.com/privacy/",
    "terms_url": "https://boardwalkai.com/terms/"
  },
  "integration_paths": {
    "claude_integrations_oauth": {
      "audience": "paying_boardwalk_customers_non_technical",
      "summary": "Primary experience for construction PMs, BD reps, and other subscribers: connect once inside Claude (Settings → Connectors), sign in with Boardwalk, no API key or config files.",
      "status": "live",
      "connect_page_url": "https://boardwalkai.com/connect/claude/",
      "mcp_server_url": "https://mcp.boardwalkai.com/mcp",
      "claude_install_url": "https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Boardwalk&connectorUrl=https%3A%2F%2Fmcp.boardwalkai.com%2Fmcp",
      "claude_admin_install_url": "https://claude.ai/admin-settings/connectors?modal=add-custom-connector&connectorName=Boardwalk&connectorUrl=https%3A%2F%2Fmcp.boardwalkai.com%2Fmcp",
      "oauth": {
        "authorization_server_metadata": "https://data.civicstar.ai/.well-known/oauth-authorization-server",
        "authorization_server_metadata_legacy": "https://data.civicstar.ai/oauth/.well-known/oauth-authorization-server",
        "registration_endpoint": "https://data.civicstar.ai/oauth/register",
        "protected_resource_metadata": "https://mcp.boardwalkai.com/.well-known/oauth-protected-resource",
        "protected_resource_metadata_mcp_path": "https://mcp.boardwalkai.com/.well-known/oauth-protected-resource/mcp",
        "token_endpoint_auth": "public_client_pkce_with_dcr",
        "redirect_uri_claude": "https://claude.ai/api/mcp/auth_callback"
      },
      "user_flow": [
        "User opens https://boardwalkai.com/connect/claude/ and clicks Add Boardwalk in Claude (or uses the claude_install_url deeplink directly)",
        "Claude opens Settings → Connectors with name Boardwalk and MCP URL https://mcp.boardwalkai.com/mcp pre-filled",
        "User clicks Add, then Connect → OAuth login with Boardwalk credentials → Allow access",
        "User enables Boardwalk in chat via + → Connectors; Claude invokes MCP tools without the user naming Boardwalk"
      ],
      "authentication": "oauth2_pkce",
      "requirements": {
        "boardwalk": "Active paid subscription with API / integration access",
        "claude_plan": "Remote MCP requires a paid Claude tier (Pro, Max, Team, or Enterprise)"
      }
    },
    "rest_api_bearer_key": {
      "audience": "developers_internal_tools_cursor_chatgpt_actions",
      "summary": "Direct HTTPS calls with a Boardwalk-issued API key. Used by copy-paste skills, scripts, and clients that do not use Claude OAuth connectors.",
      "authentication": "http_bearer",
      "this_file_supports": [
        "Discovering base URLs, OpenAPI location, and skill URLs",
        "Consistent tool naming and model routing copy for custom MCP bridges",
        "Environment variable conventions for API keys"
      ]
    }
  },
  "api": {
    "openapi_spec_url": "https://boardwalkai.com/api/reference.json",
    "openapi_spec_url_legacy": "https://data.civicstar.ai/api/reference.json",
    "swagger_ui_url": "https://data.civicstar.ai/api/reference",
    "human_docs_repository_path": "docs/civicstar-data-api.md"
  },
  "servers": [
    {
      "url": "https://data.civicstar.ai/api/v1",
      "description": "Production"
    },
    {
      "url": "https://s.civicstar.ai/api/v1",
      "description": "Staging"
    }
  ],
  "authentication": {
    "type": "http",
    "scheme": "bearer",
    "header": "Authorization",
    "value_format": "Bearer {api_key}",
    "environment_variables": [
      {
        "name": "BOARDWALK_API_KEY",
        "description": "Preferred env var for scripts, CI, and local agents",
        "aliases": ["CIVICSTAR_API_KEY"]
      }
    ],
    "key_format_hint": "Boardwalk API keys are documented in OpenAPI as Bearer credentials (e.g. csk_ prefix where applicable)"
  },
  "skills": {
    "base_url": "https://boardwalkai.com/skills",
    "urls": {
      "claude": "https://boardwalkai.com/skills/claude.md",
      "cursor": "https://boardwalkai.com/skills/cursor.md",
      "chatgpt": "https://boardwalkai.com/skills/chatgpt.md"
    },
    "note": "Skills are the API-key path for Claude Projects. For Claude Connectors (remote MCP + OAuth), use connect_page_url instead."
  },
  "tool_selection_guidance": {
    "call_when": "The user cares about pre-permit or early-stage real estate development intelligence: pipelines, filings, zoning, approvals, competitors, feasibility in a geography, or what projects are active in a city/county/state—even if they never say Boardwalk.",
    "avoid_when": "The task has no land-use or development-market angle (generic email drafting, unrelated coding, pure web lookup with no pipeline need). Precise tool descriptions reduce unnecessary calls."
  },
  "tools": [
    {
      "name": "search_projects",
      "method": "GET",
      "path": "/projects/search",
      "credits_per_project_returned": 1,
      "readOnlyHint": true,
      "destructiveHint": false,
      "description_for_models": "Search Boardwalk's database of land use and development projects extracted from municipal planning and meeting records across the United States. Returns rich project records (location, taxonomy/asset class, developer, units, square footage, statuses, actions/decisions). Use when the user asks about construction activity, development pipelines, competitive intelligence, zoning or approval activity, multifamily/industrial/commercial/residential projects, or what is being planned or approved in a specific place—even if they do not mention Boardwalk. Geographic filters require numeric IDs: call list_states then nested /locations endpoints to resolve stateIds, countyIds, and cityIds—never pass abbreviations or place names as filter values. Prefer narrower ID filters plus date when the user names a geography to save credits."
    },
    {
      "name": "ai_search_projects",
      "method": "POST",
      "path": "/projects/ai-search",
      "credits_per_project_returned": 2,
      "readOnlyHint": true,
      "destructiveHint": false,
      "description_for_models": "Natural-language search over the same Boardwalk project database: the query is interpreted by AI and matched with semantic plus structured retrieval. Use when the user's ask is fuzzy or conversational (e.g. large apartments near downtown approved recently) and structured filters are not obvious. Optional body filters stateIds/countyIds/cityIds must be integer IDs from /locations endpoints, not names. Warn that cost is higher per result than structured search. Same domain as search_projects."
    },
    {
      "name": "get_taxonomy",
      "method": "GET",
      "path": "/taxonomy",
      "credits_per_project_returned": 0,
      "readOnlyHint": true,
      "destructiveHint": false,
      "description_for_models": "Returns the land use taxonomy (project types, subtypes, asset classes, action types). Use before building structured filters for search_projects so type/subtype/assetClass values are valid. Free."
    },
    {
      "name": "list_states",
      "method": "GET",
      "path": "/locations/states",
      "credits_per_project_returned": 0,
      "readOnlyHint": true,
      "destructiveHint": false,
      "description_for_models": "Lists states with numeric IDs required for stateIds search filters. Always call this (and nested county/city location endpoints) before applying geographic filters—IDs only, not abbreviations or place names. Free."
    },
    {
      "name": "get_credit_balance",
      "method": "GET",
      "path": "/account/credits",
      "credits_per_project_returned": 0,
      "readOnlyHint": true,
      "destructiveHint": false,
      "description_for_models": "Returns remaining API credits and usage for the authenticated key. Use before large limit searches or when the user asks about quota. Free."
    }
  ],
  "mcp_client_hints": {
    "claude": {
      "connect_page": "https://boardwalkai.com/connect/claude/",
      "install_deeplink": "https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Boardwalk&connectorUrl=https%3A%2F%2Fmcp.boardwalkai.com%2Fmcp",
      "mcp_server_url": "https://mcp.boardwalkai.com/mcp"
    },
    "cursor": {
      "note": "Cursor remote MCP: url https://mcp.boardwalkai.com/mcp with OAuth Connect or Authorization Bearer JWT. API-key fallback: skills/cursor.md.",
      "env_example": "BOARDWALK_API_KEY=your_key_here"
    },
    "custom_gpt_and_other_openapi_clients": {
      "note": "Import https://boardwalkai.com/api/reference.json where the product supports OpenAPI Actions; align bearer auth with this manifest."
    }
  },
  "public_manifest_url": "https://boardwalkai.com/mcp/boardwalk-api-declaration.json"
}