fix(docs): X MCP guide says OAuth discovery is absent despite advertised metadata #505

Summary

The X MCP guide says api.x.com/mcp does not advertise native MCP OAuth discovery. An unauthenticated request currently receives a protected-resource metadata challenge, and both protected-resource and authorization-server metadata are served successfully. This report concerns that discovery statement only; it does not establish that a particular client's full OAuth login succeeds.

Runtime or environment

The current default branch was inspected at 5fcfe3da51461ef1c0b59a028da9c365547cad4c. The deployed Markdown guide contains the same statement. All endpoint observations below used unauthenticated HTTPS requests to the hosted service, without a bearer token or browser login. The repository has no published GitHub releases.

Steps to reproduce

1. Read tools/mcp.mdx, under “X MCP — X API” → “How it works.”
2. Send this unauthenticated, read-only request:

curl -i -sS \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  https://api.x.com/mcp

3. Follow the metadata URL advertised in WWW-Authenticate:

curl -sS https://api.x.com/.well-known/oauth-protected-resource
curl -sS https://api.x.com/.well-known/oauth-authorization-server

These probes were executed. No authenticated X API read, write, token exchange, or browser login was performed.

Expected behavior

The guide should accurately describe discovery metadata advertised by the hosted server, separately from dynamic client registration and any client-specific login requirements.

Actual behavior

The MCP request returned HTTP 401 with this challenge:

WWW-Authenticate: Bearer resource_metadata="https://api.x.com/.well-known/oauth-protected-resource"

The protected-resource endpoint returned HTTP 200 with these relevant fields:

{
  "resource": "https://api.x.com/mcp",
  "authorization_servers": ["https://api.x.com"],
  "bearer_methods_supported": ["header"]
}

The authorization-server endpoint returned HTTP 200 with these relevant fields:

{
  "issuer": "https://api.x.com",
  "authorization_endpoint": "https://x.com/i/oauth2/authorize",
  "token_endpoint": "https://api.x.com/2/oauth2/token",
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_basic"]
}

There was no registration_endpoint in that response. The guide's separate statement that there is no dynamic client registration is consistent with this observation and is not challenged here. Metadata availability alone does not prove end-to-end OAuth compatibility with every MCP client, nor that a local bridge is unnecessary in every configuration.

Evidence

• Expected source: the X MCP “How it works” paragraph.
• Failure source: The unauthenticated HTTP challenge and successful metadata responses reproduced under Actual behavior; only relevant public fields are included.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

Restoration check

Repeat the unauthenticated request and metadata fetches. The failing signal is the guide denying advertised discovery while these responses exist. A passing result describes the actual discovery behavior and keeps dynamic registration and full client authentication requirements distinct; successful metadata retrieval alone must not be presented as a verified full login.

Triage assessment

• Impact level: P3
• Assessment status: supported
• Impact basis: The setup explanation contains an inaccurate statement about advertised discovery; this reproduction establishes the documentation mismatch, not an observed failed client login or a required change to authentication behavior.
• Workaround status: unverified
• Workaround basis: The metadata can be inspected directly, but no complete alternative OAuth client setup was tested, so this report makes no claim of a verified login workaround.